Components
AvatarStack
A few people as Avatars that overlap in a row, the first on top, then a +N circle for the rest. Use it for who is typing, who has seen a message or who is in a call; for one circle that stands for a whole group, use GroupAvatar.
Preview
import { Avatar } from "@/components/ui/avatar"
import { AvatarStack } from "@/components/ui/avatar-stack"
<AvatarStack label="Linh, An and Minh">
<Avatar alt="" color="blue">LT</Avatar>
<Avatar alt="" color="green">AP</Avatar>
<Avatar alt="" color="purple">M</Avatar>
</AvatarStack>Usage
When to use
- Show a few people at once: who is typing, who has seen a message, who is in a call.
- Hint at the members of a project in a small space, with +N for the rest.
When not to use
- One circle for a whole group or team. Use GroupAvatar.
- A list of people to read and pick from. Use a list with Avatar and names.
- One person. Use Avatar.
Variants
size
The size of the avatars: the overlap and the +N circle follow it. Default: the first avatar's size, else md.
import { Avatar } from "@/components/ui/avatar"
import { AvatarStack } from "@/components/ui/avatar-stack"
<AvatarStack label="Linh, An and Minh">
<Avatar alt="" color="blue" size="sm">LT</Avatar>
<Avatar alt="" color="green" size="sm">AP</Avatar>
<Avatar alt="" color="purple" size="sm">M</Avatar>
</AvatarStack>
<AvatarStack label="Linh, An and Minh">
<Avatar alt="" color="blue">LT</Avatar>
<Avatar alt="" color="green">AP</Avatar>
<Avatar alt="" color="purple">M</Avatar>
</AvatarStack>
<AvatarStack label="Linh, An and Minh">
<Avatar alt="" color="blue" size="lg">LT</Avatar>
<Avatar alt="" color="green" size="lg">AP</Avatar>
<Avatar alt="" color="purple" size="lg">M</Avatar>
</AvatarStack>Examples
Three people
import { Avatar } from "@/components/ui/avatar"
import { AvatarStack } from "@/components/ui/avatar-stack"
<AvatarStack label="Linh, An and Minh">
<Avatar alt="" color="blue">LT</Avatar>
<Avatar alt="" color="green">AP</Avatar>
<Avatar alt="" color="purple">M</Avatar>
</AvatarStack>More than max
People past max fold into a +N circle.
import { Avatar } from "@/components/ui/avatar"
import { AvatarStack } from "@/components/ui/avatar-stack"
<AvatarStack max={3} label="Linh, An, Minh and 2 others">
<Avatar alt="" color="blue">LT</Avatar>
<Avatar alt="" color="green">AP</Avatar>
<Avatar alt="" color="purple">M</Avatar>
<Avatar alt="" color="orange">B</Avatar>
<Avatar alt="" color="teal">H</Avatar>
</AvatarStack>Seen by
Small avatars under a message say who has read it.
import { Avatar } from "@/components/ui/avatar"
import { AvatarStack } from "@/components/ui/avatar-stack"
<div className="flex items-center gap-xs text-xs text-text-secondary">
<AvatarStack size="sm">
<Avatar alt="" size="sm" color="blue">LT</Avatar>
<Avatar alt="" size="sm" color="green">AP</Avatar>
</AvatarStack>
Seen by Linh and An
</div>Do and don't
Do
- Keep max at 3 or 4; the +N circle counts the rest.
- Give every avatar the same size, and pass that size.
- Name the people in text next to the stack, or with label.
Don't
- Do not use a stack for one group; use GroupAvatar.
- Do not mix sizes in one stack.
- Do not make each avatar a link; the overlap leaves them too small to press.
Props
| Name | Type | Values | Default | Description |
|---|---|---|---|---|
| children required | node | - | - | Avatars of one size, with alt="". |
| max | number | - | 3 | How many avatars show before the rest fold into +N. |
| size | enum | sm | md | lg | - | The size of the avatars: the overlap and the +N circle follow it. Default: the first avatar's size, else md. |
| label | string | - | - | Names the stack for screen readers, such as Linh, An and 2 others. Without it the stack is hidden from them. |
Anatomy
| Part | Description |
|---|---|
| root | The row, laid out last to first so the first avatar is painted on top without a z-index. |
| item | One Avatar, overlapping the next by a quarter of its width, with a 2px ring in the color behind it. |
| more | The gray +N circle for the people past max, the size of the avatars. |
Accessibility
Role: img
- With label (EN `Linh, An and 2 others`) the stack is one image named by it; without label it is hidden from screen readers, for when the names are written next to it.
- Pass alt="" to every Avatar inside: the stack, or the text beside it, names them.
- The ring that cuts each avatar out is the color behind the stack (--ring-offset-color, the page by default), so it never adds a color of its own.
- Not interactive. To open the list of people, put the stack in a button and name the button.
Install
npx werewolf-ui add avatar-stackRun npx werewolf-ui init once in your app before adding components. Init sets up tokens, their CSS import and agent rules. Add installs this component and its dependencies while preserving your theme. See Installation for requirements and the alternative registry setup.