AvatarGroup
Show the people connected to an entity as a compact, overlapping stack.
Installation
- Install the package.
npm install @hashintel/ds-components- Import the component.
import { Avatar, AvatarGroup } from "@hashintel/ds-components";
export const EntityContributors = () => (
<AvatarGroup max={4}>
<Avatar
alt="Chris Feijoo"
src="https://avatars.githubusercontent.com/u/2991143?v=4"
placeholder={{ initials: "CF" }}
/>
<Avatar alt="Dele Okafor" placeholder={{ initials: "DO" }} />
<Avatar alt="Priya Patel" placeholder={{ initials: "PP" }} />
</AvatarGroup>
);When to use
- Do: Use AvatarGroup to show who's associated with something — an entity's contributors, a flow's participants, a workspace's members — where there's no room for names.
- Do: Use
maxto keep long collections to a predictable width — the badge summarises everyone it hides. - Do: Use
totalwhen you fetch only the first page of members, so the +N reflects the real count.
When not to use
- Don't: Don't use a group for a single person — use Avatar on its own.
- Don't: Don't use it where each person must be identifiable at a glance — given the room, list names next to individual Avatars instead.
- Don't: Don't use it as a control for choosing people — it only displays membership; use Combobox or Select to pick teammates.
Anatomy
<AvatarGroup>
<Avatar />
<Avatar />
{/* optional — replaces the automatic "+N" badge */}
<AvatarGroup.More>…</AvatarGroup.More>
</AvatarGroup>Examples
Basic
Pass Avatars as children, in order — the first renders on top of the stack. Hovering lifts the avatar under the pointer to the front.
Overflow
Use max or AvatarGroup.More to handle overflow.
With max the +N badge takes the final slot, so max={4} renders three avatars plus the badge. When children is not the size of the full set, for example its only the members you've loaded, set total to the size of the whole collection.
Or to fully control the overflow, place an <AvatarGroup.More> among the children.
Sizes
Sizes match Avatar's scale; md is the default. Set size once on the group
— any child that doesn't set its own inherits it. Or set size="custom"
and --avatar-size yourself to set a custom size.
Spacing
md (default) is the standard overlap; sm packs avatars tighter. Use sm
in dense chrome such as table rows, where the group competes for width.
Stacking order
The first avatar sits on top by default. Set lastOnTop to flip which edge
overlaps its neighbour — it reads better when the group sits against a right
edge.
Inherited size and tone
An enclosing AvatarGroup supplies size and tone to avatars that don't set
their own; an explicit prop still wins.
Interactive avatars with tooltips
Avatars keep their href/onClick behavior inside a group — the hover lift
raises the real element, so it stays clickable mid-animation. Wrap each in a
Tooltip so pointer users can read names without clicking.
Accessibility
AvatarGroup is a presentational grouping; naming and interaction live on the Avatars inside it.
What you must do
- Give every Avatar a real name as
alt— "Alex Leon", not "avatar" or an ID. - Give
AvatarGroup.Moreanaltthat states the overflow ("32 more members") — only the automatic badge names itself. - Keep
totalaccurate — the badge's +N and its announced name both derive from it.
API reference
AvatarGroup
| Prop | Type | Description |
|---|---|---|
| children | ReactNode | Avatar elements to render, in order. |
| max | number | Cap the number of avatars shown; the remainder collapse into a "+N" badge. |
| total | number default: number of avatar children | Size of the collection the avatars are drawn from, used for the "+N" count. Omit to use the number of avatar children. |
| lastOnTop | boolean default: false | Whether the last avatar sits on top of the stack instead of the first, so each avatar overlaps the one before it. |
| spacing | "sm" | "md" default: "md" | How tightly avatars overlap. |
| size | "xxs" | "xs" | "sm" | "md" | "lg" | "custom" default: "md" | Applies a size to all avatar children unless explicitly overridden |
| tone | "neutral" | "brand" default: "neutral" | Applies a tone to all avatar children unless explicitly overridden |
AvatarGroup.More
| Prop | Type | Description |
|---|---|---|
| alt | string | Accessible description of the image, e.g. "Firstname Lastname", "Organization", "Shortname (online)". |
| children | ReactNode | Content shown inside the overflow badge (e.g. "+99"). |
| onClick | MouseEventHandler<Element> | |
| href | string | |
| target | "_blank" | |
| size | "xxs" | "xs" | "sm" | "md" | "lg" | "custom" | |
| tone | "neutral" | "brand" | |
| shape | "circle" | "square" default: "circle" |
Styling
- You can customize the size of an avatar with the
--avatar-sizecustom property. The preset sizes set it for you;size="custom"leaves it to you (see Sizes above). --avatar-lift-scalesets how large a hovered avatar grows. Override it on the group when a custom size makes the default pop feel off.
Was this page helpful?