Components
Avatar stack
Avatar stack stacks a collection of avatar elements
Avatar stack is under development. If you have feedback or suggestions, please report them on Github or in Slack.
<link
rel="preload"
as="image"
href="/img/component-docs/cats/cat1.webp"
/>
<ul class="ds-avatar-stack">
<li>
<span aria-label="cat" class="ds-avatar" role="img">
<img src="/img/component-docs/cats/cat1.webp" alt=""/>
</span>
</li>
<li>
<span aria-label="briefcase" class="ds-avatar" role="img">
<svg role="img"></svg>
</span>
</li>
<li>
<span
aria-label="Søren Magnussen"
class="ds-avatar"
role="img"
>sm</span>
</li>
<li>
<span aria-label="Mark Downright" class="ds-avatar" role="img">md</span>
</li>
<li>
<span aria-label="Ola Nordman" class="ds-avatar" role="img">on</span>
</li>
</ul>const Preview = () => ( <AvatarStack> <li> <Avatar aria-label='cat'> <img src='/img/component-docs/cats/cat1.webp' alt='' /> </Avatar> </li> <li> <Avatar aria-label='briefcase'> <BriefcaseIcon /> </Avatar> </li> <li> <Avatar aria-label='Søren Magnussen'>sm</Avatar> </li> <li> <Avatar aria-label='Mark Downright'>md</Avatar> </li> <li> <Avatar aria-label='Ola Nordman'>on</Avatar> </li> </AvatarStack> ); render(<Preview />)
Use avatar stack when
- A group of people or entities should be displayed together, but space is limited.
- You need to signal that multiple people are involved, without showing everyone at full size.
Avoid avatar stack when
- There is only ever a single avatar to display.
- Each person or entity must be clearly identifiable by name or role at the same time.
Examples
Customization
Avatar stack is designed to be flexible enough to cover many different needs and use cases.
<link
rel="preload"
as="image"
href="/img/component-docs/cats/cat1.webp"
/>
<link
rel="preload"
as="image"
href="/img/component-docs/cats/cat6.webp"
/>
<fieldset
style="display:flex;align-items:center;gap:var(--ds-size-4)"
>
<div
style="display:flex;gap:var(--ds-size-3);align-items:center"
>
<ds-field class="ds-field">
<input class="ds-input" type="checkbox"/>
<label class="ds-label" data-weight="regular">Expandable</label>
</ds-field>
</div>
<ds-field class="ds-field">
<label class="ds-label">
Size
<!-- -->
64px
</label>
<input min="24" max="150" step="0.1" type="range" value="64"/>
</ds-field>
<ds-field class="ds-field">
<label class="ds-label">
Overlap
<!-- -->
32px
</label>
<input min="0" max="100" step="1" type="range" value="32"/>
</ds-field>
<ds-field class="ds-field">
<label class="ds-label">
Gap
<!-- -->
2px
</label>
<input min="0" max="15" step="1" type="range" value="2"/>
</ds-field>
<ds-field class="ds-field">
<label class="ds-label">
Radius
<!-- -->
32px
</label>
<input min="0" max="75" step="1" type="range" value="32"/>
</ds-field>
</fieldset>
<br/>
<ul
class="ds-avatar-stack"
style="--dsc-avatar-stack-gap:2px;--dsc-avatar-stack-size:64px;--dsc-avatar-stack-overlap:32px;--dsc-avatar-stack-radius:32px"
>
<li>
<span class="ds-avatar" role="img">
<img src="/img/component-docs/cats/cat1.webp" alt=""/>
</span>
</li>
<li>
<span class="ds-avatar" role="img">
<img src="/img/component-docs/cats/cat6.webp" alt=""/>
</span>
</li>
<li>
<span class="ds-avatar" role="img">md</span>
</li>
<li>
<span class="ds-avatar" role="img">
<img src="/img/component-docs/cats/cat1.webp" alt=""/>
</span>
</li>
<li>
<span class="ds-avatar" role="img">
<img src="/img/component-docs/cats/cat6.webp" alt=""/>
</span>
</li>
<li>+10</li>
</ul>const Playground = () => { const [expandable, setExpandable] = useState(false); const [overlap, setOverlap] = useState(32); const [radius, setRadius] = useState(32); const [size, setSize] = useState(64); const [gap, setGap] = useState(2); return ( <> <fieldset style={{ display: 'flex', alignItems: 'center', gap: 'var(--ds-size-4)', }} > <div style={{ display: 'flex', gap: 'var(--ds-size-3)', alignItems: 'center', }} > <Checkbox label='Expandable' checked={expandable} onChange={() => setExpandable(!expandable)} /> </div> <Field> <Label>Size {`${size}px`}</Label> <input min='24' max='150' step='0.1' type='range' value={size} onChange={(e) => setSize(e.target.valueAsNumber)} /> </Field> <Field> <Label>Overlap {`${overlap}px`}</Label> <input min='0' max='100' step='1' type='range' value={overlap} onChange={(e) => setOverlap(e.target.valueAsNumber)} /> </Field> <Field> <Label>Gap {`${gap}px`}</Label> <input min='0' max='15' step='1' type='range' value={gap} onChange={(e) => setGap(e.target.valueAsNumber)} /> </Field> <Field> <Label>Radius {`${radius}px`}</Label> <input min='0' max='75' step='1' type='range' value={radius} onChange={(e) => setRadius(e.target.valueAsNumber)} /> </Field> </fieldset> <br /> <AvatarStack expandable={expandable || undefined} style={ { '--dsc-avatar-stack-size': `${size}px`, '--dsc-avatar-stack-gap': `${gap}px`, '--dsc-avatar-stack-overlap': `${overlap}px`, '--dsc-avatar-stack-radius': `${radius}px`, } as React.CSSProperties } > <li> <Avatar aria-label=''> <img src='/img/component-docs/cats/cat1.webp' alt='' /> </Avatar> </li> <li> <Avatar aria-label=''> <img src='/img/component-docs/cats/cat6.webp' alt='' /> </Avatar> </li> <li> <Avatar aria-label=''>md</Avatar> </li> <li> <Avatar aria-label=''> <img src='/img/component-docs/cats/cat1.webp' alt='' /> </Avatar> </li> <li> <Avatar aria-label=''> <img src='/img/component-docs/cats/cat6.webp' alt='' /> </Avatar> </li> <li>+10</li> </AvatarStack> </> ); }; render(<Playground />)
Variants
Avatar stack supports both round and square variants, but only one variant per stack.
<link
rel="preload"
as="image"
href="/img/component-docs/cats/cat1.webp"
/>
<link
rel="preload"
as="image"
href="/img/component-docs/cats/cat2.webp"
/>
<link
rel="preload"
as="image"
href="/img/component-docs/cats/cat3.webp"
/>
<link
rel="preload"
as="image"
href="/img/component-docs/cats/cat4.webp"
/>
<ul
class="ds-avatar-stack"
data-expandable="true"
tabindex="0"
style="--dsc-avatar-stack-radius:var(--ds-border-radius-md)"
aria-label="example of square avatars"
>
<li>
<span aria-label="variant square" class="ds-avatar" role="img"></span>
</li>
<li>
<span aria-label="Ola Nordmann" class="ds-avatar" role="img">
<img src="/img/component-docs/cats/cat1.webp" alt=""/>
</span>
</li>
<li>
<span aria-label="Ola Nordmann" class="ds-avatar" role="img">
<img src="/img/component-docs/cats/cat2.webp" alt=""/>
</span>
</li>
<li>
<span aria-label="Ola Nordmann" class="ds-avatar" role="img">
<img src="/img/component-docs/cats/cat3.webp" alt=""/>
</span>
</li>
<li>
<span aria-label="Ola Nordmann" class="ds-avatar" role="img">
<img src="/img/component-docs/cats/cat4.webp" alt=""/>
</span>
</li>
</ul>const Radius = () => ( <AvatarStack aria-label='example of square avatars' expandable style={ { '--dsc-avatar-stack-radius': 'var(--ds-border-radius-md)', } as React.CSSProperties } > <li> <Avatar aria-label='variant square' /> </li> <li> <Avatar aria-label='Ola Nordmann'> <img src='/img/component-docs/cats/cat1.webp' alt='' /> </Avatar> </li> <li> <Avatar aria-label='Ola Nordmann'> <img src='/img/component-docs/cats/cat2.webp' alt='' /> </Avatar> </li> <li> <Avatar aria-label='Ola Nordmann'> <img src='/img/component-docs/cats/cat3.webp' alt='' /> </Avatar> </li> <li> <Avatar aria-label='Ola Nordmann'> <img src='/img/component-docs/cats/cat4.webp' alt='' /> </Avatar> </li> </AvatarStack> ); render(<Radius />)
Indicating avatars not shown
When there are more avatars than can be displayed in the stack, there are two different ways to indicate this.
<link
rel="preload"
as="image"
href="/img/component-docs/cats/cat1.webp"
/>
<ul class="ds-avatar-stack">
<li>
<span class="ds-avatar" role="img">
<img src="/img/component-docs/cats/cat1.webp" alt=""/>
</span>
</li>
<li>
<span class="ds-avatar" role="img">
<svg role="img"></svg>
</span>
</li>
<li>
<span class="ds-avatar" role="img">sm</span>
</li>
<li>
<span
class="ds-avatar"
role="img"
data-color="neutral"
style="--dsc-avatar-font-size:1.1rem"
>+14</span>
</li>
</ul>
<ul class="ds-avatar-stack">
<li>
<span class="ds-avatar" role="img">
<img src="/img/component-docs/cats/cat1.webp" alt=""/>
</span>
</li>
<li>
<span class="ds-avatar" role="img">
<svg role="img"></svg>
</span>
</li>
<li>
<span class="ds-avatar" role="img">sm</span>
</li>
<li>
<span class="ds-avatar" role="img">on</span>
</li>
<li>+14</li>
</ul>const AdditionalAvatars = () => ( <> <AvatarStack> <li> <Avatar aria-label=''> <img src='/img/component-docs/cats/cat1.webp' alt='' /> </Avatar> </li> <li> <Avatar aria-label=''> <BriefcaseIcon /> </Avatar> </li> <li> <Avatar aria-label=''>sm</Avatar> </li> <li> <Avatar data-color='neutral' aria-label='' style={{ '--dsc-avatar-font-size': '1.1rem' } as React.CSSProperties} > +14 </Avatar> </li> </AvatarStack> <AvatarStack> <li> <Avatar aria-label=''> <img src='/img/component-docs/cats/cat1.webp' alt='' /> </Avatar> </li> <li> <Avatar aria-label=''> <BriefcaseIcon /> </Avatar> </li> <li> <Avatar aria-label=''>sm</Avatar> </li> <li> <Avatar aria-label=''>on</Avatar> </li> <li>+14</li> </AvatarStack> </> ); render(<AdditionalAvatars />)
Tooltips and links
Avatars in avatar stack can have tooltips and be links, but be aware of accessibility considerations.
<link
rel="preload"
as="image"
href="/img/component-docs/cats/cat1.webp"
/>
<link
rel="preload"
as="image"
href="/img/component-docs/cats/cat6.webp"
/>
<div style="display:flex;flex-wrap:wrap;gap:var(--ds-size-4)">
<fieldset>
<legend>Link + Tooltip</legend>
<ul class="ds-avatar-stack" aria-label="contributors">
<li>
<a
href="#"
aria-label="Ola Katt"
class="ds-avatar"
data-tooltip="Ola Katt"
tabindex="0"
data-placement="top"
data-autoplacement="true"
>
<img src="/img/component-docs/cats/cat1.webp" alt=""/>
</a>
</li>
<li>
<a
href="#"
aria-label="Kari Katt"
class="ds-avatar"
data-tooltip="Kari Katt"
tabindex="0"
data-placement="top"
data-autoplacement="true"
>
<img src="/img/component-docs/cats/cat6.webp" alt=""/>
</a>
</li>
<li>
<a
href="#"
aria-label="Katt 2"
class="ds-avatar"
data-tooltip="Katt 2"
tabindex="0"
data-placement="top"
data-autoplacement="true"
>
<img src="/img/component-docs/cats/cat1.webp" alt=""/>
</a>
</li>
<li>
<a
href="#"
aria-label="Børge Katt"
class="ds-avatar"
data-tooltip="Børge Katt"
tabindex="0"
data-placement="top"
data-autoplacement="true"
>BK</a>
</li>
</ul>
</fieldset>
<fieldset>
<legend>Link + Tooltip expandable</legend>
<ul
class="ds-avatar-stack"
data-expandable="fixed"
tabindex="0"
aria-label="contributors"
>
<li>
<a
href="#"
aria-label="Ola Katt"
class="ds-avatar"
data-tooltip="Ola Katt"
tabindex="0"
data-placement="top"
data-autoplacement="true"
>
<img src="/img/component-docs/cats/cat6.webp" alt=""/>
</a>
</li>
<li>
<a
href="#"
aria-label="Kari Katt"
class="ds-avatar"
data-tooltip="Kari Katt"
tabindex="0"
data-placement="top"
data-autoplacement="true"
>
<img src="/img/component-docs/cats/cat1.webp" alt=""/>
</a>
</li>
<li>
<a
href="#"
aria-label="Katt 2"
class="ds-avatar"
data-tooltip="Katt 2"
tabindex="0"
data-placement="top"
data-autoplacement="true"
>
<img src="/img/component-docs/cats/cat6.webp" alt=""/>
</a>
</li>
<li>
<a
href="#"
aria-label="Børge Katt"
class="ds-avatar"
data-tooltip="Børge Katt"
tabindex="0"
data-placement="top"
data-autoplacement="true"
>BK</a>
</li>
</ul>
</fieldset>
</div>const WithTooltipAndLink = () => ( <div style={{ display: 'flex', flexWrap: 'wrap', gap: 'var(--ds-size-4)' }}> <fieldset> <legend>Link + Tooltip</legend> <AvatarStack aria-label='contributors'> <li> <Tooltip content='Ola Katt'> <Avatar aria-label='' asChild> <a href='#'> <img src='/img/component-docs/cats/cat1.webp' alt='' /> </a> </Avatar> </Tooltip> </li> <li> <Tooltip content='Kari Katt'> <Avatar aria-label='' asChild> <a href='#'> <img src='/img/component-docs/cats/cat6.webp' alt='' /> </a> </Avatar> </Tooltip> </li> <li> <Tooltip content='Katt 2'> <Avatar aria-label='' asChild> <a href='#'> <img src='/img/component-docs/cats/cat1.webp' alt='' /> </a> </Avatar> </Tooltip> </li> <li> <Tooltip content='Børge Katt'> <Avatar aria-label='' asChild> <a href='#'>BK</a> </Avatar> </Tooltip> </li> </AvatarStack> </fieldset> <fieldset> <legend>Link + Tooltip expandable</legend> <AvatarStack expandable='fixed' aria-label='contributors'> <li> <Tooltip content='Ola Katt'> <Avatar aria-label='' asChild> <a href='#'> <img src='/img/component-docs/cats/cat6.webp' alt='' /> </a> </Avatar> </Tooltip> </li> <li> <Tooltip content='Kari Katt'> <Avatar aria-label='' asChild> <a href='#'> <img src='/img/component-docs/cats/cat1.webp' alt='' /> </a> </Avatar> </Tooltip> </li> <li> <Tooltip content='Katt 2'> <Avatar aria-label='' asChild> <a href='#'> <img src='/img/component-docs/cats/cat6.webp' alt='' /> </a> </Avatar> </Tooltip> </li> <li> <Tooltip content='Børge Katt'> <Avatar aria-label='' asChild> <a href='#'>BK</a> </Avatar> </Tooltip> </li> </AvatarStack> </fieldset> </div> ); render(<WithTooltipAndLink />)
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.
Text
Remember to provide context to screen readers about what the stack represents, for example "Meeting participants" or "Team members".
Edit this page on github.com (opens in a new tab)