Skip to content

docs(avatar stack): team review #5018

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mimarz merged 9 commits into from
Jun 29, 2026
Merged

docs(avatar stack): team review #5018

Show file tree
Hide file tree
Changes from 7 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
fa12a33
docs(avatar stack): team review
mrosvik Jun 19, 2026
ee30e55
Merge branch 'main' into docs-avatarstack
mrosvik Jun 19, 2026
79e3f64
biome
Barsnes Jun 22, 2026
d600dba
english
mrosvik Jun 24, 2026
0fd47c7
Merge branch 'docs-avatarstack' of https://github.com/digdir/designsy…
mrosvik Jun 24, 2026
79e3434
Update apps/www/app/content/components/avatar-stack/no/code.mdx
mimarz Jun 24, 2026
86eb90f
Merge branch 'main' into docs-avatarstack
mimarz Jun 24, 2026
2c9cdc6
Update apps/www/app/content/components/avatar-stack/en/code.mdx
mimarz Jun 29, 2026
d66d014
Merge branch 'main' into docs-avatarstack
mimarz Jun 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
132 changes: 35 additions & 97 deletions apps/www/app/content/components/avatar-stack/avatar-stack.stories.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,15 +10,15 @@ import { useState } from 'react';

export const Preview = () => (
<EXPERIMENTAL_AvatarStack>
<Avatar aria-label=''>
<Avatar aria-label='cat'>
<img src='/img/component-docs/cats/cat1.webp' alt='' />
</Avatar>
<Avatar aria-label=''>
<Avatar aria-label='briefcase'>
<BriefcaseIcon />
</Avatar>
<Avatar aria-label='' initials='sm' />
<Avatar aria-label=''>md</Avatar>
<Avatar aria-label='' initials='on' />
<Avatar aria-label='Søren Magnussen'>sm</Avatar>
<Avatar aria-label='Mark Downright'>md</Avatar>
<Avatar aria-label='Ola Nordman'>on</Avatar>
</EXPERIMENTAL_AvatarStack>
);

Expand Down Expand Up @@ -208,91 +208,29 @@ export const ShapeVariants = () => (
);

export const DataSize = () => (
<div style={{ display: 'flex', flexWrap: 'wrap', gap: 'var(--ds-size-8)' }}>
<fieldset>
<legend>avatarSize='var(--ds-size-8)'</legend>
<EXPERIMENTAL_AvatarStack avatarSize={'var(--ds-size-8)'}>
<Avatar aria-label=''>
<img src='/img/component-docs/cats/cat6.webp' alt='' />
</Avatar>
<Avatar aria-label=''>
<img src='/img/component-docs/cats/cat1.webp' alt='' />
</Avatar>
<Avatar aria-label=''>
<img src='/img/component-docs/cats/cat6.webp' alt='' />
</Avatar>
<Avatar aria-label=''>
<img src='/img/component-docs/cats/cat1.webp' alt='' />
</Avatar>
</EXPERIMENTAL_AvatarStack>
</fieldset>
<fieldset>
<legend>avatarSize='3em'</legend>
<EXPERIMENTAL_AvatarStack avatarSize='3em'>
<Avatar aria-label=''>
<img src='/img/component-docs/cats/cat6.webp' alt='' />
</Avatar>
<Avatar aria-label=''>
<img src='/img/component-docs/cats/cat1.webp' alt='' />
</Avatar>
<Avatar aria-label=''>
<img src='/img/component-docs/cats/cat6.webp' alt='' />
</Avatar>
<Avatar aria-label=''>
<img src='/img/component-docs/cats/cat1.webp' alt='' />
</Avatar>
</EXPERIMENTAL_AvatarStack>
</fieldset>
<fieldset>
<legend>avatarSize='clamp(2rem, 1.5rem + 2vw, 4rem)'</legend>
<EXPERIMENTAL_AvatarStack avatarSize='clamp(2rem, 1.5rem + 2vw, 4rem)'>
<Avatar aria-label=''>
<img src='/img/component-docs/cats/cat6.webp' alt='' />
</Avatar>
<Avatar aria-label=''>
<img src='/img/component-docs/cats/cat1.webp' alt='' />
</Avatar>
<Avatar aria-label=''>
<img src='/img/component-docs/cats/cat6.webp' alt='' />
</Avatar>
<Avatar aria-label=''>
<img src='/img/component-docs/cats/cat1.webp' alt='' />
</Avatar>
</EXPERIMENTAL_AvatarStack>
</fieldset>
</div>
<EXPERIMENTAL_AvatarStack avatarSize='clamp(5rem, 1.5rem + 2vw, 10rem)'>
<Avatar aria-label=''>
<img src='/img/component-docs/cats/cat6.webp' alt='' />
</Avatar>
<Avatar aria-label=''>
<img src='/img/component-docs/cats/cat1.webp' alt='' />
</Avatar>
<Avatar aria-label=''>
<img src='/img/component-docs/cats/cat6.webp' alt='' />
</Avatar>
<Avatar aria-label=''>
<img src='/img/component-docs/cats/cat1.webp' alt='' />
</Avatar>
</EXPERIMENTAL_AvatarStack>
);

export const Gap = () => (
<div style={{ display: 'flex', flexWrap: 'wrap', gap: 'var(--ds-size-8)' }}>
<fieldset>
<legend>gap='2px'</legend>
<EXPERIMENTAL_AvatarStack avatarSize='3rem' gap='2px'>
<Avatar aria-label='' initials='AA' />
<Avatar aria-label='' initials='BB' />
<Avatar aria-label='' initials='CC' />
<Avatar aria-label='' initials='DD' />
</EXPERIMENTAL_AvatarStack>
</fieldset>
<fieldset>
<legend>gap='4px'</legend>
<EXPERIMENTAL_AvatarStack avatarSize='3rem' gap='4px'>
<Avatar aria-label='' initials='AA' />
<Avatar aria-label='' initials='BB' />
<Avatar aria-label='' initials='CC' />
<Avatar aria-label='' initials='DD' />
</EXPERIMENTAL_AvatarStack>
</fieldset>
<fieldset>
<legend>gap='6px'</legend>
<EXPERIMENTAL_AvatarStack avatarSize='3rem' gap='6px'>
<Avatar aria-label='' initials='AA' />
<Avatar aria-label='' initials='BB' />
<Avatar aria-label='' initials='CC' />
<Avatar aria-label='' initials='DD' />
</EXPERIMENTAL_AvatarStack>
</fieldset>
</div>
<EXPERIMENTAL_AvatarStack avatarSize='3rem' gap='6px'>
<Avatar aria-label='' initials='AA' />
<Avatar aria-label='' initials='BB' />
<Avatar aria-label='' initials='CC' />
<Avatar aria-label='' initials='DD' />
</EXPERIMENTAL_AvatarStack>
);

export const AdditionalAvatars = () => (
Expand Down Expand Up @@ -331,30 +269,30 @@ export const WithTooltipAndLink = () => (
<fieldset>
<legend>Link + Tooltip</legend>
<EXPERIMENTAL_AvatarStack overlap={20} aria-label='contributors'>
<Tooltip content='Ola Nordmann'>
<Tooltip content='Ola Katt'>
<Avatar aria-label='' asChild>
<a href='#'>
<img src='/img/component-docs/cats/cat1.webp' alt='' />
</a>
</Avatar>
</Tooltip>
<Tooltip content='Kari Nordmann'>
<Tooltip content='Kari Katt'>
<Avatar aria-label='' asChild>
<a href='#'>
<img src='/img/component-docs/cats/cat6.webp' alt='' />
</a>
</Avatar>
</Tooltip>
<Tooltip content='Person 2'>
<Tooltip content='Katt 2'>
<Avatar aria-label='' asChild>
<a href='#'>
<img src='/img/component-docs/cats/cat1.webp' alt='' />
</a>
</Avatar>
</Tooltip>
<Tooltip content='Person 3'>
<Tooltip content='Børge Katt'>
<Avatar aria-label='' asChild>
<a href='#'>BR</a>
<a href='#'>BK</a>
</Avatar>
</Tooltip>
</EXPERIMENTAL_AvatarStack>
Expand All @@ -366,30 +304,30 @@ export const WithTooltipAndLink = () => (
expandable='fixed'
aria-label='contributors'
>
<Tooltip content='Ola Nordmann'>
<Tooltip content='Ola Katt'>
<Avatar aria-label='' asChild>
<a href='#'>
<img src='/img/component-docs/cats/cat6.webp' alt='' />
</a>
</Avatar>
</Tooltip>
<Tooltip content='Kari Nordmann'>
<Tooltip content='Kari Katt'>
<Avatar aria-label='' asChild>
<a href='#'>
<img src='/img/component-docs/cats/cat1.webp' alt='' />
</a>
</Avatar>
</Tooltip>
<Tooltip content='Person 2'>
<Tooltip content='Katt 2'>
<Avatar aria-label='' asChild>
<a href='#'>
<img src='/img/component-docs/cats/cat6.webp' alt='' />
</a>
</Avatar>
</Tooltip>
<Tooltip content='Person 3'>
<Tooltip content='Børge Katt'>
<Avatar aria-label='' asChild>
<a href='#'>BR</a>
<a href='#'>BK</a>
</Avatar>
</Tooltip>
</EXPERIMENTAL_AvatarStack>
Expand Down
53 changes: 4 additions & 49 deletions apps/www/app/content/components/avatar-stack/en/code.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,49 +8,8 @@ Avatar stack is under development. If you have feedback or suggestions, please r

To create an avatar stack in plain HTML, use the `ds-avatar-stack` class on a `<span>`. Inside this, place elements with the `ds-avatar` class. Note that if you want to use `data-expandable="fixed"`, the number of avatars must be specified via `--dsc-avatar-count: <number>` to correctly calculate the fixed width. Use `data-suffix` to add a text indicator for hidden avatars.

```html
<span
class="ds-avatar-stack"
data-expandable="fixed"
style="--dsc-avatar-count: 3;"
tabindex="0"
aria-label="contributors"
data-suffix="+4">
<span
class="ds-avatar"
data-variant="circle"
role="img"
aria-label=""
>
<img alt="" aria-hidden="true" src="...">
</span>
<span
class="ds-avatar"
data-variant="circle"
data-initials="ON"
role="img"
aria-label=""
></span>
<span
class="ds-avatar"
data-variant="circle"
role="img"
aria-label=""
>
<span>ON</span>
</span>
</span>
```

To override the default gap/size/overlap, use these CSS variables:
`aria-label` or `aria-description` can be used on avatar stack to provide context to screen readers about what the stack represents.

```css
.ds-avatar-stack {
--dsc-avatar-stack-gap: 4px; /* default is 2px */
--dsc-avatar-stack-avatar-size: 3rem; /* default is var(--ds-size-12) */
--dsc-avatar-stack-overlap: 30; /* default is 50 */
}
```

## CSS variables and data attributes

Expand All @@ -62,12 +21,8 @@ Avatar stack uses its own CSS variables to control gap, size and overlap.

## Examples

### Customization
Avatar stack is designed to be flexible enough to cover many different needs and use cases.
<Story story="Playground" layout='block' />

### Expandable
`expandable` animates overlap to 0 on hover or focus. Use `expandable="fixed"` to expand with overflow without changing the physical width. `tabindex="0"` is automatically added with `expandable`, but this can be overridden.
`data-expandable` animates overlap to 0 on hover or focus. Use `data-expandable="fixed"` to expand with overflow without changing the physical width. `tabindex="0"` is automatically added with `data-expandable`, but this can be overridden.
Comment thread
mimarz marked this conversation as resolved.
Outdated
<Story story="Expandable" layout='block' />

### Indicating avatars not shown
Expand All @@ -76,11 +31,11 @@ You can also use an avatar with `+xx` as `initials` or child, but you should ove
<Story story="AdditionalAvatars" layout='block' />

### Sizes
You cannot use `data-size` to change the size of avatars in an avatar stack. Instead, the size is controlled via the `avatarSize` prop on `AvatarStack`. This must be specified in a valid CSS length unit (`px`, `em`, `rem`, `var(--ds-size-6)`, etc.).
You cannot use `data-size` to change the size of avatars in an avatar stack. Instead, the size is controlled by setting the `--dsc-avatar-stack-size` variable.
<Story story="DataSize" layout='block' />

### Gap
Avatar stack uses CSS `mask` to create the visible space between avatars. The default is 2px, but can be customized with `gap`.
Avatar stack uses CSS `mask` to create the visible space between avatars. This can be adjusted by setting the `--dsc-avatar-stack-gap` variable.
<Story story="Gap" layout='block' />

## React
Expand Down
16 changes: 1 addition & 15 deletions apps/www/app/content/components/avatar-stack/en/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,18 +23,6 @@ Avatar stack is under development. If you have feedback or suggestions, please r
Avatar stack is designed to be flexible enough to cover many different needs and use cases.
<Story story="Playground" layout='block' />

### Sizes
The size of avatars in an avatar stack is controlled via `avatarSize` and can be specified in any valid CSS size unit for maximum flexibility.
<Story story="DataSize" layout='block' />

### Gap
The visible space between avatars can be customized with `gap`
<Story story="Gap" layout='block' />

### Expandable
In some cases, it may be desirable to expand the stack on hover and focus. This functionality is off by default.
<Story story="Expandable" layout='block' />

### Variants
Avatar stack supports both round and square variants, but only one variant per stack.
<Story story="ShapeVariants" layout='block' />
Expand All @@ -50,7 +38,5 @@ Avatars in avatar stack can have tooltips and be links, but be aware of accessib
## Guidelines
Avatar stack should be used with caution, as it can be challenging for users to identify individual avatars in a tightly packed stack. Ensure that the use of avatar stack makes sense in the context of the user experience and does not compromise accessibility or usability.

Avatar stack does not support wrapping across multiple lines. If there are more avatars than can fit in the stack, you can use `suffix` or an additional avatar with `+xx` to indicate the number of hidden avatars.

## Text
`aria-label` or `aria-description` can be used on avatar stack to provide context to screen readers about what the stack represents, for example "Meeting participants" or "Team members".
Remember to provide context to screen readers about what the stack represents, for example "Meeting participants" or "Team members".
55 changes: 6 additions & 49 deletions apps/www/app/content/components/avatar-stack/no/code.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,49 +8,8 @@ Avatar stack er under utvikling. Har du tilbakemelding eller innspill, meld fra

For å lage en avatar stack i ren HTML brukes klassen `ds-avatar-stack` på en `<span>`. Inne i denne plasseres elementer med klassen `ds-avatar`. Merk at dersom du vil bruke `data-expandable="fixed"` må antallet avatarer være oppgitt via `--dsc-avatar-count: <number>` for å korrekt kalkulere den faste bredden. Bruk `data-suffix` for å legge til en tekstindikator for skjulte avatarer.

```html
<span
class="ds-avatar-stack"
data-expandable="fixed"
style="--dsc-avatar-count: 3;"
tabindex="0"
aria-label="contributors"
data-suffix="+4">
<span
class="ds-avatar"
data-variant="circle"
role="img"
aria-label=""
>
<img alt="" aria-hidden="true" src="...">
</span>
<span
class="ds-avatar"
data-variant="circle"
data-initials="ON"
role="img"
aria-label=""
></span>
<span
class="ds-avatar"
data-variant="circle"
role="img"
aria-label=""
>
<span>ON</span>
</span>
</span>
```

Dersom du vil overstyre standard gap/size/overlap gjøres det via disse CSS-variablene:
`aria-label` eller `aria-description` kan brukes på avatar stack for å gi kontekst til skjermlesere om hva stabelen representerer.

```css
.ds-avatar-stack {
--dsc-avatar-stack-gap: 4px; /* standard er 2px */
--dsc-avatar-stack-avatar-size: 3rem; /* standard er var(--ds-size-12) */
--dsc-avatar-stack-overlap: 30; /* standard er 50 */
}
```

## CSS variabler og data-attributter

Expand All @@ -62,25 +21,23 @@ Avatar stack bruker egne CSS-variabler for å styre gap, størrelse og overlapp.

## Eksempel

### Tilpassbarhet
Avatar stack er laget for å være fleksibel nok til å dekke mange ulike behov og brukstilfeller.
<Story story="Playground" layout='block' />

### Expandable
`expandable` animerer overlap til 0 ved hover eller fokus. Bruk `expandable="fixed"` for å utvide med overflow uten å endre den fysiske bredden. `tabindex="0"` blir automatisk lagt med `expandable`, men dette kan overstyres.
`data-expandable` animerer overlap til 0 ved hover eller fokus. Bruk `data-expandable="fixed"` for å utvide med overflow uten å endre den fysiske bredden. `tabindex="0"` blir automatisk lagt til med `data-expandable`, men dette kan overstyres.
<Story story="Expandable" layout='block' />

### Indikere avatarer som ikke vises
Avatar stack støtter ikke "wrapping" over flere linjer. Dersom det er flere avatarer enn det er plass til i stacken, kan man bruke `suffix` for å indikere dette i form av tekst til høyre for stabelen. Denne skalerer seg automatisk med avatar-størrelsen.

Det er også mulig å bruke en avatar med `+xx` som `initials` eller child, men da bør du overstyre tekststørrelsen på denne avataren med `--dsc-avatar-font-size` dersom det skal være plass til tosifret eller høyere tall.

<Story story="AdditionalAvatars" layout='block' />

### Størrelser
Du kan ikke bruke `data-size` for å endre størrelsen på avatarer i en avatar stack. I stedet styres størrelsen via `avatarSize` prop på `AvatarStack`. Denne må oppgis i en gyldig CSS-lengdeenhet (`px`, `em`, `rem`, `var(--ds-size-6)` osv.).
Du kan ikke bruke `data-size` for å endre størrelsen på avatarer i en avatar stack. I stedet styres størrelsen med å sette størrelsen på variabelen `--dsc-avatar-stack-size`.
<Story story="DataSize" layout='block' />

### Gap
Avatar stack bruker CSS `mask` for å lage det synlige mellomrommet mellom avatarene. Standard er 2px, men kan tilpasses med `gap`.
Avatar stack bruker CSS `mask` for å lage det synlige mellomrommet mellom avatarene, denne kan justeres ved sette størrelsen på variabelen `--dsc-avatar-stack-gap`.
<Story story="Gap" layout='block' />

## React
Expand Down
Loading
Loading