Skip to Content
BBRICKSv0.7.4
KitPrimitives

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.

avatarStack
KeyEnglishArabic
moreand {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

  1. Stack (span.kit-stack, role="img", aria-label).
  2. Faces: the first max people as Avatars (seeded by id), each after the first pulled 9px under the previous one.
  3. More (.kit-stack-more, aria-hidden, dir="ltr"): "+N", 12px 700 --ink-3.

Variants

PropValueLookWhen
max4 (default)Up to four facesGroup cards
max3, 5 …That many facesDrawer heads (3), challenge footers
moretrue (default)"+N" after the facesWhen no count is written nearby
morefalseFaces onlyWhen the count sits next to it ("4 creators")
totalnumber"+N" counts total − faces shownThe API sends only the first few faces

States

StateTriggerLook
Fewpeople.length ≤ max and no totalFaces only, no "+N"
Overflowmore people than max"+N"
Initials onlyno avatarUrlColoured initials circles
Emptypeople=[]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 total when the API sends a preview of members.
  • Turn more off 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.

See also: Button · ButtonLink · CouponChip

Source

src/kit/primitives/AvatarStack.tsx (line 31) on GitHub.

On this page