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.

Sienna Hewitt
Avatar
Size
Primitives
Shape
import { Avatar } from "@/components/base/avatar/avatar"; <Avatar src="https://www.untitledui.com/images/avatars/sienna-hewitt?fm=webp&q=80" alt="Sienna Hewitt" size="2xl" status="online" />

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.

The components in this family, with their descriptions and import paths
ComponentDescriptionImport from
AvatarThe core avatar: a photo, initials, or a placeholder, with one badge slot.@/​components/​base/​avatar/​avatar
AvatarLabelGroupAn avatar beside a title and subtitle, for people lists and account menus.@/​components/​base/​avatar/​avatar-label-group
AvatarProfilePhotoAn oversized ringed avatar for profile headers and settings pages.@/​components/​base/​avatar/​avatar-profile-photo
AvatarGroupA DrumKit-authored row of overlapping avatars with a +N overflow and an optional add button.@/​components/​base/​avatar/​avatar-group
AvatarAddButtonA dashed circular button with a tooltip, for inviting people to a group.@/​components/​base/​avatar/​base-components
AvatarOnlineIndicatorThe presence dot the status prop renders; usable standalone at 8 sizes.@/​components/​base/​avatar/​base-components
VerifiedTickThe blue verified tick the verified prop renders, at the same 8 sizes.@/​components/​base/​avatar/​base-components
AvatarCompanyIconA small company logo for the badge slot, pinned to the bottom-right corner.@/​components/​base/​avatar/​base-components
AvatarCountThe 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

Unlike its siblings, 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.

Variants by size across the columns and content down the rows
xssmmdlgxl2xl
photo
Sienna Hewitt
Sienna Hewitt
Sienna Hewitt
Sienna Hewitt
Sienna Hewitt
Sienna Hewitt
initials
SH
SH
SH
SH
SH
SH
placeholder

Hover and focus states are live. Interact with any cell.

Primitives

Variants by size across the columns and addOn down the rows
xssmmdlgxl2xl
none
Ammar Foley
Ammar Foley
Ammar Foley
Ammar Foley
Ammar Foley
Ammar Foley
online
Ammar Foley
Ammar Foley
Ammar Foley
Ammar Foley
Ammar Foley
Ammar Foley
offline
Ammar Foley
Ammar Foley
Ammar Foley
Ammar Foley
Ammar Foley
Ammar Foley
avatar
Ammar Foley
Layers
Ammar Foley
Layers
Ammar Foley
Layers
Ammar Foley
Layers
Ammar Foley
Layers
Ammar Foley
Layers
verified
Ammar Foley
Ammar Foley
Ammar Foley
Ammar Foley
Ammar Foley
Ammar Foley
count
Ammar Foley
2
Ammar Foley
2
Ammar Foley
2
Ammar Foley
2
Ammar Foley
2
Ammar Foley
2

Hover and focus states are live. Interact with any cell.

One badge slot, fixed priority

The add-ons share a single slot: 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

Olly Schroeder
Olly Schroeder
Olly Schroeder
Olly Schroeder
Olly Schroeder
Olly Schroeder
rounded={false}
Olly Schroeder
Olly Schroeder
Olly Schroeder
Olly Schroeder
Olly Schroeder
Olly Schroeder
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 Wilkinson

pippa@untitledui.com

sm
Mathilde Lewis

Mathilde Lewis

mathilde@untitledui.com

md
Caitlyn King

Caitlyn King

caitlyn@untitledui.com

lg

Truncation

Mathilde Lewis

Mathilde Lewis

mathilde.lewis@a-very-long-company-name.example.com

Only the subtitle truncates

The subtitle carries 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.

Caitlyn King
sm
Caitlyn King
md
Caitlyn King
lg

Content forms and add-ons

Pippa Wilkinson
verified
Ammar Foley
status
MK
initials
placeholder

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.

Sienna Hewitt
Ammar Foley
Pippa Wilkinson
Olly Schroeder
Mathilde Lewis
Caitlyn King
+5
xs
Sienna Hewitt
Ammar Foley
Pippa Wilkinson
Olly Schroeder
Mathilde Lewis
Caitlyn King
+5
sm
Sienna Hewitt
Ammar Foley
Pippa Wilkinson
Olly Schroeder
Mathilde Lewis
Caitlyn King
+5
md

The overflow is literal

Past 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.

AvatarAddButton

The one interactive member: a dashed circular button that invites someone to the group of avatars it follows. It wraps its icon in a tooltip and reuses the tooltip title as the accessible name. Three sizes, mirrored from the size union in avatar-add-button.tsx, matching the three smallest Avatar sizes.

Variants by size
xssmmd

Hover and focus states are live. Interact with any cell.

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

Offline
AvatarOnlineIndicator
Online
AvatarOnlineIndicator
Avatar
LayersAvatarCompanyIcon
Verified tick
VerifiedTick
Count
8
AvatarCount

The 9+ clamp

9
9+
Constant side padding, so the 9+ pill widens

The clamp is built in

Anything past nine renders as 9+: the right pill above is count 99. The two-character form keeps the same side padding, so the pill grows by exactly the width of the extra character.

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

rest, hover and focus live
isDisabled

Focusable, inside a link

Tab to it; the ring is live

The wrapper does the focusing

An avatar is never focusable by itself. 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.