Person mark with photo or initials, optional presence, and a stacked overflow group.
Also known as: user avatar, profile photo, avatar stack
Install with the CLI, or copy the component source into your project.
Add avatar (npm)
1npx --yes -p @default-file/ui df-ui add avatar
Initials from the display name at size md. Omit src, or let a failed image fall back to the same initials.
Face sizes from xs to lg. Default is md.
Circle clip by default. Square uses the medium radius token.
Status dot tones for online, away, busy, and offline. Omit presence to hide the dot.
AvatarStack shows faces up to max, then an overflow chip for the rest. Circle and square share the same max.
Person mark with optional photo, generated initials fallback, presence tone, and a stacked overflow group.
| Prop | Type | Default | Notes |
|---|---|---|---|
| name | string | - | Required display name. Drives initials, default title, default image label, and the tone color. |
| src | string | null | - | Image URL. Sanitized before load. On failure or omit, initials render instead. |
| alt | string | - | Accessible name for the loaded image. Defaults to name. |
| size | "xs" | "sm" | "md" | "lg" | "md" | Face size step. |
| shape | "circle" | "square" | "circle" | Clip shape. |
| presence | "online" | "away" | "busy" | "offline" | - | Status dot tone. Omit to hide the dot. The dot has its own accessible name from the string catalogue. |
| className | string | - | Additional styles on the root. |
Image name (alt): When src loads, the image uses alt (defaulting to name). Initials fallback is aria-hidden; the root title defaults to name and is not an ARIA name. Presence (status): The presence dot carries a catalogue aria-label for its tone.
| Prop | Type | Default | Notes |
|---|---|---|---|
| items | AvatarStackItem[] | - | People to show. Each item needs id and name; src and presence are optional. |
| max | number | 3 | How many faces to show before an overflow chip. The overflow chip announces how many more. |
| size | "xs" | "sm" | "md" | "lg" | "md" | Size for every face and the overflow chip. |
| shape | "circle" | "square" | "circle" | Shape for every face and the overflow chip. |
| className | string | - | Additional styles on the stack. |