Avatar Stack

Overlapping avatars for showing a group of users at a glance. Supports an overflow badge when the count exceeds a maximum.

Atom

Avatar

When To Use

Use Avatar Stack when you need a reusable atoms pattern instead of rebuilding the structure from primitives.
Start from the simplest example that fits the task, then add decoration only when it clarifies meaning or hierarchy.
Review the examples below to understand the tradeoffs between density, emphasis, and behavior.

When Not To Use

Do not use Avatar Stack just because it already exists in the catalog; choose the pattern that matches the task, not the most decorative option.
Do not keep layering options onto the pattern when a simpler component or section would be easier to understand and maintain.

Accessibility Notes

Keep headings, labels, and supporting text in the DOM before decorative chrome so the page reads well without styles or scripts.
Test the pattern with keyboard navigation and a screen reader before treating the visual layout as complete.
Use status, selection, and disabled states that remain understandable without color alone.

Key Props / API

Props

avatars, max, size, className

Example Code

import { AvatarStack } from "@hilum/ui"

<AvatarStack
  avatars={[
    { name: "Sofia P.", fallback: "SP", colorClass: "bg-brand-primary text-white" },
    { name: "Marcus K.", fallback: "MK", colorClass: "bg-brand-secondary text-ground-900" },
    { name: "Rachel T.", fallback: "RT", colorClass: "bg-brand-secondary text-ground-900" },
    { name: "James W.", fallback: "JW", colorClass: "bg-ground-900 text-white" },
  ]}
/>

Avatar Stack · Basic

Default

Four stacked avatars

SPMKRTJW

Avatar Stack · Overflow

With max + overflow

Collapses to +N when exceeding max

SPMKRT+3

SPMKRTJW+2

SPMKRTJWAL+1

Avatar Stack · Sizes

sm · md · lg

Three size variants

SPMKRTJW

Avatar Stack · In context

With accompanying text

Stack + supporting label

SPMKRTJW+2

Sofia and 2 others are viewing