Avatars
Avatars put a face to a person or entity, falling back from photo to initials to a placeholder, with one badge slot for presence, verification, or a count.
Avatars
Avatars put a face to a person or entity, falling back from photo to initials to a placeholder, with one badge slot for presence, verification, or a count.
Demo
Change the props and copy the result. The Avatar control picks the content form, and Primitives fills the badge slot.
The family
Reach for the standard Avatar for almost everything. AvatarLabelGroup adds the name and detail line a people list needs, AvatarProfilePhoto is the oversized version for profile headers, AvatarGroup overlaps several people into one row, and AvatarAddButton is the one interactive member, for inviting people. The last four are the badge primitives the add-on props render, exported for composing your own. Each name links to its section below.
| Component | Description | Import from |
|---|---|---|
| Avatar | The core avatar: a photo, initials, or a placeholder, with one badge slot. | @/components/base/avatar/avatar |
| AvatarLabelGroup | An avatar beside a title and subtitle, for people lists and account menus. | @/components/base/avatar/avatar-label-group |
| AvatarProfilePhoto | An oversized ringed avatar for profile headers and settings pages. | @/components/base/avatar/avatar-profile-photo |
| AvatarGroup | A DrumKit-authored row of overlapping avatars with a +N overflow and an optional add button. | @/components/base/avatar/avatar-group |
| AvatarAddButton | A dashed circular button with a tooltip, for inviting people to a group. | @/components/base/avatar/base-components |
| AvatarOnlineIndicator | The presence dot the status prop renders; usable standalone at 8 sizes. | @/components/base/avatar/base-components |
| VerifiedTick | The blue verified tick the verified prop renders, at the same 8 sizes. | @/components/base/avatar/base-components |
| AvatarCompanyIcon | A small company logo for the badge slot, pinned to the bottom-right corner. | @/components/base/avatar/base-components |
| AvatarCount | The red numeric badge the count prop renders; 16px through lg, then 18 and 20, capping at 9+. | @/components/base/avatar/base-components/avatar-count |
AvatarCount imports from its own module
AvatarCount is not re-exported from the base-components index, so its import path is the full base-components/avatar-count module as shown above.Avatar
The core component: one circle, three content forms, and a single badge slot. The content form is not a prop you set; it is a fallback chain, so a photo avatar given initials degrades to them if the image fails. Every size and content combination follows, mirrored from the size union in avatar.tsx.
| xs | sm | md | lg | xl | 2xl | |
|---|---|---|---|---|---|---|
| photo | ||||||
| initials | SH | SH | SH | SH | SH | SH |
| placeholder |
Hover and focus states are live. Interact with any cell.
Primitives
| xs | sm | md | lg | xl | 2xl | |
|---|---|---|---|---|---|---|
| none | ||||||
| online | ||||||
| offline | ||||||
| avatar | ||||||
| verified | ||||||
| count | 2 | 2 | 2 | 2 | 2 | 2 |
Hover and focus states are live. Interact with any cell.
One badge slot, fixed priority
status wins over verified, which wins over count, which wins over badge. They never stack; details are on the Guidelines tab. Each add-on runs its own scale: the dot holds a 10px floor through md before stepping to 12, 14, and 16, the tick a 14px floor through md before stepping to 16, 18, and 20, and the avatar badge and count a 16px floor through lg before stepping to 18 and 20. Past nine the count renders 9+.Shape and border
AvatarLabelGroup
An avatar with the name and one detail line beside it, for people lists, account menus, and assignee rows. It always draws the avatar border, and every Avatar prop passes through, so status and verified work here too. Three sizes, mirrored from the size union in avatar-label-group.tsx.
Pippa Wilkinson
pippa@untitledui.com
Mathilde Lewis
mathilde@untitledui.com
Caitlyn King
caitlyn@untitledui.com
Truncation
Mathilde Lewis
mathilde.lewis@a-very-long-company-name.example.com
Only the subtitle truncates
truncate and clips with an ellipsis in a narrow column; the title does not, and wraps instead. Both read straight from the classes in avatar-label-group.tsx.AvatarProfilePhoto
The oversized member for profile headers and settings pages: a white ring, an elevation shadow at md and lg, and the same content fallback chain as Avatar. Its add-on badges render at the three largest indicator sizes, which exist for exactly this component. Three sizes, mirrored from the size union in avatar-profile-photo.tsx.
Content forms and add-ons
count is accepted but never rendered
AvatarProfilePhotoProps extends AvatarProps, so count, border, and rounded type-check here, but the component only renders the status, verified, and badge add-ons and is always circular. What compiles is wider than what renders.AvatarGroup
A row of overlapping avatars for showing who is on a project or thread. Each member wears the Figma sheet’s 1.5px separation ring as an internal border, neighbors tuck 4, 8, or 12px underneath, anyone past max collapses into a +N avatar, and addButtonTitle appends the invite button. DrumKit-authored: upstream ships no avatar group component, so avatar-group.tsx has no upstream counterpart and upgrades never touch it. Three sizes, matching the three smallest Avatar sizes.
The overflow is literal
max, the remainder renders as a +N avatar: text-quaternary on bg-tertiary, styled like an initials placeholder rather than the red AvatarCount, and it never clamps, so 47 hidden people read +47. The add button renders only when addButtonTitle names it, because the tooltip reuses the title as the accessible name.Badge primitives
The pieces the add-on props render, exported for composing your own arrangements. The Figma status icon sheet names 5 types, which map onto 4 primitives: the online indicator carries the offline and online types, the company icon renders the avatar type using the sheet’s Layers placeholder artwork, and the verified tick and count badge are one type each. Each primitive runs its own scale across the avatar sizes: the indicator a 10px floor through md before stepping to 12, 14, and 16, the tick a 14px floor through md before stepping to 16, 18, and 20, and the company icon and count a 16px floor through lg before stepping to 18 and 20. Past nine, the count clamps to 9+ and widens into a pill with its side padding held constant.
The five types
AvatarOnlineIndicatorAvatarOnlineIndicator
AvatarCompanyIconVerifiedTickAvatarCountThe 9+ clamp
The clamp is built in
States
Most of the family is static imagery with no interactive states. The two below are the ones that genuinely exist: the add button’s rest, hover, focus, and disabled states, and the focus ring a focusable avatar shows when its wrapping link has keyboard focus.
AvatarAddButton states
Focusable, inside a link
The wrapper does the focusing
focusable only draws the ring when a wrapping element carrying the group class has visible keyboard focus, so the link or button around it owns the tab stop and the accessible name.