Avatar
A round picture of a person with a hairline rim, initials on a tint when there is no image, an optional presence badge and an overlapping group. Source: src/components/ui/avatar.tsx.
Sizes
Three sizes: sm for dense rows and groups, default beside a line of text, lg beside a two-line name block.
Fallback
AvatarFallback renders whenever the image is missing, still loading or fails. Use two initials at default and lg, one at sm, where the text drops to 12px.
Badge
AvatarBadge pins to the bottom-right with a ring in the canvas colour. Empty, it is a presence dot; with an icon it marks a role or a verified state. Its size follows the avatar.
Group
AvatarGroup overlaps its avatars by 8px and rings each one in the canvas colour so the edges read. End with AvatarGroupCount for the overflow; it matches the size of the avatars inside.
With a name
The common composition: an avatar beside a name and a second line. The name is the label, so the image's alt goes empty.
Mara Lindqvist
mara@acme.dev
Dan Okafor
dan@acme.dev
Priya Raman
priya@acme.dev
Props
| Prop | Type | Default | Description |
|---|---|---|---|
| size | "sm" | "default" | "lg" | "default" | Avatar only. 24, 32 or 40px, mirrored as data-size. A plain union, not a cva variant. |
| src, alt | string | — | AvatarImage. The image renders only once it has loaded; until then, or on error, the fallback shows. |
| delayMs | number | — | AvatarFallback (Radix). Wait before showing the fallback, so a fast image never flashes initials. |
| className | string | — | Every part. Merged last; set the presence colour on AvatarBadge with a token such as bg-success. |
| ...props | Radix Avatar.Root / Image / Fallback; span (Badge); div (Group, GroupCount) | — | Native attributes pass through. |
Best practices
When to use
- A person: an author, an assignee, a member. For an app, an agent or a file type, use an IconTile instead.
- Groups for shared ownership or presence; cap at three or four and show the rest as a count.
Behavior
- Always pass a fallback: images 404, load late or are blocked.
- Sizes are a hand-written union outside cva; there is no xs (20px) or xl. Need one? Add it to the component rather than overriding size-* per call.
- No in-app screen uses Avatar yet; this page is its reference.
Accessibility
- Give AvatarImage the person's name as alt when the avatar stands alone; empty alt when the name is printed beside it.
- A presence dot is colour only. Say the state in text nearby or in an aria-label on the row.
- AvatarGroupCount is plain text ("+4"); if it opens a list, wrap it in a Button with an aria-label such as "4 more members".
Content
- Initials: first and last name, uppercase, at most two letters.
- Use real photos or initials, never a logo or brand mark as a stand-in for a person.