AvatarStack
The v3 mock's .stack: up to max overlapping 34px avatars and "+N" for the rest (a group card's members; total counts people beyond the faces sent). One image to AT, named with the people shown and how many more ("Laila Saeed, Karim Hosny and 3 more"). No people, no stack: an image with no name is noise to a screen reader (the card around it says how many members it has).
import { AvatarStack } from '@ergasti/bricks';Examples
Initials and sizes
With no picture an avatar draws the name's initials on a tone chosen by seed, so the same person keeps the same colour.
Code
import { Avatar } from '@ergasti/bricks';
function Sizes() {
return (
<div style={{ display: 'flex', gap: 12, alignItems: 'center' }}>
<Avatar name="Laila Saeed" seed={0} size="sm" />
<Avatar name="Karim Hosny" seed={1} />
<Avatar name="Salma Hosny" seed={2} size="lg" />
<Avatar name="سارة علي" seed={3} size="lg" />
</div>
);
}Pictures
src replaces the initials; if the picture fails to load the initials come back.
Code
import { Avatar } from '@ergasti/bricks';
import { blocksData } from './sample-data';
function Pictures() {
return (
<div style={{ display: 'flex', gap: 12, alignItems: 'center' }}>
<Avatar name="Laila Saeed" seed={0} size="lg" src={blocksData.photo(0)} />
<Avatar name="Broken link" seed={1} size="lg" src="data:image/png;base64,AAAA" />
</div>
);
}Avatar stack
Overlapping avatars with a "+N" count past max; total counts people beyond the faces you have (5 sent, 12 in the group: "+8"); more={false} draws the faces only, where a count is said nearby.
Code
import { AvatarStack } from '@ergasti/bricks';
import { blocksData } from './sample-data';
function Stack() {
const people = ['Laila Saeed', 'Karim Hosny', 'Salma Hosny', 'Mariam Adel', 'Youssef Saeed', 'Hana Hosny', 'Ali Hosny'].map((name, id) => ({ id, name, avatarUrl: blocksData.photo(id) }));
return (
<div style={{ display: 'grid', gap: 12 }}>
<AvatarStack people={people} />
<AvatarStack people={people} max={3} />
<AvatarStack people={people.slice(0, 5)} total={12} />
<AvatarStack people={people} max={3} more={false} />
</div>
);
}Props
Prop
Type
Labels
Every word this component draws, in both languages. Override one per component and language with BricksProvider labels under the key avatarStack, or with the component's own prop where it has one. A {name} is a value the component fills in.
| Key | English | Arabic |
|---|---|---|
more | and {n} more | و{n} كمان |
separator | , | ، |
Design guidance
How the BRICKS design system uses AvatarStack. Written in docs/content/components/AvatarStack.md; the props above are read from the code, which wins where the two disagree.
A row of up to four overlapping avatars with "+N" for the rest; use it to show who is in a group or a challenge at a glance.
AvatarStack is the v3 mock's .stack: 34px avatars overlapping by 9px with a 2px card-coloured ring, followed by a muted bold "+N". It is one image to assistive tech, named with the people shown and the remainder ("Laila Saeed, Karim Hosny and 3 more"). With no people it renders nothing, because an unnamed image is noise; the surrounding card already says how many members there are.
Anatomy
- Stack (
span.kit-stack,role="img",aria-label). - Faces: the first
maxpeople asAvatars (seeded byid), each after the first pulled 9px under the previous one. - More (
.kit-stack-more,aria-hidden,dir="ltr"): "+N", 12px 700--ink-3.
Variants
| Prop | Value | Look | When |
|---|---|---|---|
max | 4 (default) | Up to four faces | Group cards |
max | 3, 5 … | That many faces | Drawer heads (3), challenge footers |
more | true (default) | "+N" after the faces | When no count is written nearby |
more | false | Faces only | When the count sits next to it ("4 creators") |
total | number | "+N" counts total − faces shown | The API sends only the first few faces |
States
| State | Trigger | Look |
|---|---|---|
| Few | people.length ≤ max and no total | Faces only, no "+N" |
| Overflow | more people than max | "+N" |
| Initials only | no avatarUrl | Coloured initials circles |
| Empty | people=[] | Nothing rendered (null) |
Usage
A group card's members:
<AvatarStack people={group.members.slice(0, 5)} total={group.memberCount} />The group drawer head, with the count written beside it:
<DrawerHead tone="lime" title="Ramadan glow squad" sub="4 creators"
lead={<AvatarStack people={members} max={3} more={false} />} />A PR challenge card footer:
<div style={{ display: 'flex', gap: 8, alignItems: 'center' }}>
<AvatarStack people={joinedPreview} max={4} more={false} />
<span><b>38</b> joined</span>
</div>Where it appears
- Brand › Creators › Groups › group cards (5 faces + "+N") and the group drawer head (3 faces).
- PR Portal › Affiliate programs › Challenges › challenge card footer (faces, then "{n} joined"; the mock draws them without "+N").
- Screens: Creators, PR · Affiliate programs.
Guidelines
Do
- Pass
totalwhen the API sends a preview of members. - Turn
moreoff when a visible count already says how many.
Don't
- Don't show more than 5 faces; the overlap stops reading as a group.
- Don't make it clickable on its own; make the card or row the target.
RTL and Arabic
- The overlap uses
margin-inline-start, so the stack runs right to left in Arabic. - "+N" stays
dir="ltr"; the spoken remainder uses the Arabic copy.
Tokens
--card (ring), --ink-3 ("+N"), plus Avatar's tone tokens.
Accessibility
role="img"with a name built from the shown names (joined with ", " / "، ") plus "and N more"; the inner avatars and "+N" are hidden.- Empty stack renders nothing, so there is no unnamed image.
Found in the source
- Roles in the markup:
img. - ARIA attributes set:
aria-label,aria-hidden. - Its tests cover: “is not a control (nothing focusable)”.
Read from the component's source and tests. See Accessibility for the patterns the library follows.
Related
Avatar: one face.PersonCell: one person with name and sub line.
See also: Button · ButtonLink · CouponChip
Source
src/kit/primitives/AvatarStack.tsx (line 31) on GitHub.