Components
GroupAvatar
One circle the size of an Avatar for a group, split into tiles instead of stacked: one member fills it, two split it in halves, three take a half and two quarters, four or more take four quarters with +N for the rest. Use it for a group chat or a team.
Preview
import { GroupAvatar } from "@/components/ui/group-avatar"
const designTeam = [{ name: "Linh Tran" }, { name: "An Pham" }, { name: "Minh Le" }, { name: "Bao Do" }]
<GroupAvatar alt="Design team" members={designTeam} />Usage
When to use
- Stand for a group chat or a team with one circle, such as in ConversationList.
- Show a group's members inside the space of one Avatar.
When not to use
- Show several people side by side. Use AvatarStack.
- One person. Use Avatar.
- A workspace or brand with its own logo. Use Avatar with src.
Variants
size
sm 24px, md 32px, lg 40px, as Avatar.
import { GroupAvatar } from "@/components/ui/group-avatar"
const designTeam = [{ name: "Linh Tran" }, { name: "An Pham" }, { name: "Minh Le" }, { name: "Bao Do" }]
<GroupAvatar size="sm" alt="Design team" members={designTeam} />
<GroupAvatar alt="Design team" members={designTeam} />
<GroupAvatar size="lg" alt="Design team" members={designTeam} />Examples
Group sizes
Two, three, four and more members.
import { GroupAvatar } from "@/components/ui/group-avatar"
const pairMembers = [{ name: "Linh Tran" }, { name: "An Pham" }]
const trioMembers = [{ name: "Linh Tran" }, { name: "An Pham" }, { name: "Minh Le" }]
const designTeam = [{ name: "Linh Tran" }, { name: "An Pham" }, { name: "Minh Le" }, { name: "Bao Do" }]
const companyMembers = [{ name: "Linh Tran" }, { name: "An Pham" }, { name: "Minh Le" }, { name: "Bao Do" }, { name: "Hoa Vu" }, { name: "Khoa Ngo" }]
<div className="flex items-center gap-md">
<GroupAvatar alt="Linh and An" members={pairMembers} />
<GroupAvatar alt="Launch crew" members={trioMembers} />
<GroupAvatar alt="Design team" members={designTeam} />
<GroupAvatar alt="Company" members={companyMembers} />
</div>Beside a name
With the group's name written next to it, alt is empty.
import { GroupAvatar } from "@/components/ui/group-avatar"
const designTeam = [{ name: "Linh Tran" }, { name: "An Pham" }, { name: "Minh Le" }, { name: "Bao Do" }]
<div className="flex items-center gap-sm">
<GroupAvatar alt="" size="lg" members={designTeam} />
<span className="text-sm font-medium text-text-primary">Design team</span>
</div>Do and don't
Do
- Use lg next to two lines of text, as in ConversationList.
- Pass photos when you have them; letters are the fallback.
- Keep the members' order stable, so the circle does not change between visits.
Don't
- Do not use it for a list of people to tell apart; use AvatarStack.
- Do not use sm for groups of three or more where letters matter; the tiles are too small for them.
- Do not put a status dot on a tile; put it on the circle.
Props
| Name | Type | Values | Default | Description |
|---|---|---|---|---|
| members required | { name: string; src?: string; initials?: string; color?: "gray" | "red" | "orange" | "yellow" | "green" | "teal" | "blue" | "purple" | "pink" }[] | - | - | The members to show, in order. Up to four show; past four, three show and the fourth tile counts the rest. color defaults to blue, green, purple, orange. |
| alt required | string | - | - | The name of the group, such as Design team. Pass an empty string when the name is written next to it. |
| size | enum | sm | md | lg | md | sm 24px, md 32px, lg 40px, as Avatar. |
Anatomy
| Part | Description |
|---|---|
| root | The circle: 24, 32 or 40px, cut round, holding a grid of tiles with a 2px gap. |
| tile | One member: their photo, or the first letter of their initials or name on a soft hue pair. In the 24px circle a split tile shows its color alone. |
| more | The gray tile with +N (9+ above 9) when the group has more than four members. |
Accessibility
Role: img
- alt names the group (EN `Design team`) on the circle, one image for screen readers. Pass alt="" when the name is written next to it.
- The tiles, their letters and photos are hidden from screen readers; the group's name is what counts.
- The hues are decoration, as on Avatar.
Install
npx werewolf-ui add group-avatarRun 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.