Skip to main content
Digitaltableteur

Design system components

AvatarGroup

Overlapping stack of Avatars with a +N overflow bubble.

Status: beta. Group: display. Markdown version: /design-system/components/avatar-group.md

When to use

AvatarGroup answers "who is on this?" at a glance: the first max Avatars overlap into a stack and the remainder collapses into a +N bubble that also announces itself to screen readers. Pass same-size Avatars and set the matching group size (sm=2rem, md=2.5rem, lg=3rem) so the bubble lines up.

When not to use

  • Do not use the +N bubble as a button; if the full roster matters, link to it separately.

Look-alikes

The contract names no look-alike with a deciding condition.

Props

AvatarGroup props
PropTypeDefaultDescriptionRequired
ariaLabelstringnoneAccessible name for the cluster (e.g. "Project members").No
maxnumber4Avatars beyond this count collapse into a "+N" bubble.No
size"sm" | "md" | "lg"mdSize of the overflow bubble; children Avatars should match (sm=2rem, md=2.5rem, lg=3rem).No
childrenReact.ReactNodenoneNo description in the contract.Yes

Variants

  • Available sizes: sm, md, lg (default md).

Invalid combinations

The contract records no invalid combinations.

Keyboard

AvatarGroup keyboard behaviour
KeyBehaviour
TabReaches clickable Avatars only; static stacks have no stops.

Rules

Every item under When not to use is a MUST NOT. MUST and SHOULD follow RFC 2119.

AvatarGroup rules
LevelRuleHow it is checked
MUSTARIA: Role=group with aria-label naming the cluster.Not yet verified: no evidence record. WCAG 4.1.2.
MUSTARIA: Overflow bubble announces 'N more' via sr-only text.Not yet verified: no evidence record. WCAG 4.1.2.
MUSTRequired stories produce no axe violations at the configured severity.Automated by npm run test:stories:matrix:ci. WCAG 2.5.8.
MUSTThe accessibility tree (role, name, state) matches the committed snapshot for every required story.Automated by npm run test:stories:matrix:ci. WCAG 1.3.1, 4.1.2.
MUSTThe component remains legible and operable under a real browser forced-colors: active pass.Automated by npm run test:stories:hc.
MUSTEvery documented keyboard interaction works as specified.Not yet verified: no evidence record. WCAG 2.1.1, 2.1.2.
MUSTA human completed an end-to-end accessibility review of this component.Manual review, last on 2026-07-03.
SHOULDKeep max between 3 and 5; past that the stack stops being scannable and the +N carries the message.Not stated in the contract.
SHOULDMatch children Avatar sizes to the group size so the overflow bubble aligns with the faces.Not stated in the contract.
SHOULDName the cluster with ariaLabel ("Project members"); the group role reads it before the names.Not stated in the contract.
SHOULDOrder children by relevance; the first faces are the ones people see.Not stated in the contract.
SHOULD NOTDo not mix Avatar sizes in one stack; the overlap rhythm breaks.Not stated in the contract.

Install and import

  • Install: npm install @digitaltableteur/react (version 0.9.1, restricted access on npm).
  • Import: import { AvatarGroup } from "@digitaltableteur/react";
  • Entry point: @digitaltableteur/react/identity exports it too.
  • Styles: import @digitaltableteur/react/style.css once at the app boundary.
  • Also available as the custom element <dt-avatar-group>; see the custom elements manifest.

Links