Avatar
FreeShow who a person is, or what a workspace or team is, with initials or an icon.
npx wunderui-cli add avatarPlayground
Installation
npx wunderui-cli add avatarWrites the source into your project with its dependencies and, on first use, the styles - see Installation.
Then import what you need:
import {
Avatar,
AvatarBadge,
AvatarFallback,
AvatarImage,
AvatarLabel,
} from "@/components/ui/avatar"
import type {
AvatarBadgeStatus,
AvatarColor,
AvatarLabelProps,
} from "@/components/ui/avatar"Then use it:
import { Avatar, AvatarFallback } from "@/components/ui/avatar"
export function Owner() {
return (
<Avatar color="indigo">
<AvatarFallback>NL</AvatarFallback>
</Avatar>
)
}Expected result: You should see one round 36 px avatar with the indigo tint and the initials NL.
When to use
Use Avatar for
- Showing who a person is next to their name, a comment or an activity entry
- Showing what a workspace, team or project is, with a square avatar
- The account button of an app bar, or a choice of a person in a picker
Use something else for
- Avatar Group for several people in a row, composed by hand with a hover effect or passed as data with people and a limit
- Person Cell for an avatar with a name and a role in a table or a list
Types
Use a circle for a person and a square for a workspace, team or project. It holds initials or an icon.
Appearance
The tone is an identity colour: keep one hue per person. It never means status.
Sizes
Five sizes. Initials, icon and presence dot scale with them, so never resize an avatar with classes.
Presence
A dot sits on the top right corner. Each status has its own shape, so colour is never the only signal.
States
An interactive avatar is a button, for account menus and pickers, and shows a halo on hover. A plain avatar has no states.
Label
AvatarLabel puts a name and a second line, such as a role or an email, next to an avatar. size picks the avatar (default 36, lg 40, xl 44 px), compact sets the text in 12 and 11 px, capacity adds a load bar, and trailing holds a control such as a menu button. The two lines sit without a gap, so a 14 px name and a 12 px second line are exactly as tall as the 36 px avatar; tight={false} adds 2 px. Padding and corners come from className. It replaces PersonCell and UserInfo.
Keyboard interactions
A plain avatar is not interactive and has no keyboard behaviour. An interactive avatar is a native button.
- TaborShift+Tab
- Moves focus to or away from an interactive avatar. A disabled one is skipped.
- EnterorSpace
- Presses the avatar, for example to open an account menu or to choose a person.
Behavior and motion
What the avatar does with state, content, the DOM and motion.
- Image and fallback
- The fallback stays in place until the image has loaded, and when the URL fails; you can delay it to avoid a flash for a fast image. The tint sits on the frame behind the image.
- Size
- The size sets the frame (24, 28, 36, 40 or 44 px) and scales initials, icon and presence dot with it. Initials and counts are centred on cap height, so they look centred in any font.
- Presence dot
- The badge sits on the top right corner: its centre is on the edge of a circle, or on the rounded corner of a square. With a status it is an image named by the status; override with aria-label.
- Interactive
- An interactive avatar is a button with aria-pressed from selected. Hover draws a 3 px halo in the page tone, a press the subtle tone, keyboard focus the focus ring, and disabled dims it to 40 %.
- Selected
- Selected adds a check badge on the top right corner, where the presence dot sits, and keeps the subtle halo on an interactive avatar.
- Names for screen readers
- Initials are real text, so a screen reader reads NL before the name. When the name is printed beside the avatar, hide the avatar from assistive technology and give the image an empty alt.
- Motion
- The avatar has no motion of its own: the halo of an interactive avatar changes at once.
- Reduced motion
- Nothing animates, so reduced motion needs no fallback here. In Avatar Group the hover lift is switched off.
Anatomy
The parts the component is made of. Each one renders a you can target from CSS.
- 1data-slot="avatar"
The round or square frame in five sizes. Set a colour for tinted initials or the primary variant for a filled one; interactive makes it a button, selected adds a check badge and disabled dims it.
- data-slot="avatar-image"Optional
The photo, an img with src and alt. It shows once loaded; until then, or when the URL fails, the fallback stays in place.
- 2data-slot="avatar-fallback"
Initials or an icon, shown while the image loads or when there is none. The text size follows the avatar size.
- 3data-slot="avatar-badge"Optional
A dot on the top right corner, centred on the circle's edge or the square's corner. A status sets a presence dot with a shape per status and an accessible name that defaults to the status.
- data-slot="avatar-check"Optional
- data-slot="avatar-label"Optional
An avatar with a name and a second line, and optionally a capacity bar or a control at the end. It is a plain div. It replaces PersonCell and UserInfo, which still render the same row.
- Optional
- Optional
Best practices
- Do
Always add a fallback with initials, also when there is an image. It covers the moment before the photo loads and a broken image URL.
- Do
Use a circle for a person and a square for an entity such as a workspace, team or project, so the shape already tells which one it is.
- Do
Keep one colour per person. The tints are theme tokens, so initials stay readable in dark mode.
- Do
Show presence with the badge and say it in text where it matters, such as Away next to the name. Each status has its own shape, so colour is never the only signal.
- Do
Give an interactive avatar an accessible name with aria-label, for example Account menu, Nora Lindgren. Its initials are not a name.
- Don’t
Don't resize an avatar with your own size classes. Pick one of the sizes: initials, icon and presence dot scale with it.
- Don’t
Don't use colour to carry status or meaning. Tone is an identity colour; status needs the presence dot, a word, or both.
- Don’t
Don't combine selected with a presence dot. The check badge and the dot sit on the same corner, so one hides the other.
- Do
Next to a single 20 px line of text use size="3xs", so the avatar is as tall as the text.
API reference
One table per part, in the order of the anatomy. Every part also takes the props of the Base UI part it wraps (such as , and ) and the native attributes of its element.
The round or square frame in five sizes. Set a colour for tinted initials or the primary variant for a filled one; interactive makes it a button, selected adds a check badge and disabled dims it.
| Prop | Type | Default | Description |
|---|---|---|---|
| size | "3xs" | "sm" | "xs" | "default" | "lg" | "xl" | — | The size of the frame: is 24 px, 28 px, 36 px, 40 px and 44 px. Initials, icon and presence dot scale with it. |
| shape | "circle" | "square" | — | for a person, for an entity such as a workspace, team or project. The square has a medium corner radius. |
| variant | "plain" | "primary" | — | is a muted fill with a hairline border. fills the frame with the primary colour and sets the initials in the colour on primary. |
| color | "indigo" | "blue" | "purple" | "pink" | "red" | "orange" | "yellow" | "green" | "alternative" | "grey" | — | A soft tint for initials: the tint colour behind and the matching tint text colour on top. Use one hue per person, and do not combine it with . |
| interactive | boolean | — | Renders the avatar as a with hover, pressed and focus states. Pass , because the initials are not a name. |
| selected | boolean | — | Marks the avatar as chosen: a check badge on the top right corner. With it also draws the subtle halo and sets . |
| disabled | boolean | — | Dims an interactive avatar to 40 % and removes pointer events. It has no effect on a plain avatar. |
The photo, an img with src and alt. It shows once loaded; until then, or when the URL fails, the fallback stays in place.
| Prop | Type | Default | Description |
|---|---|---|---|
| keepMounted | boolean | false | Keeps the image in the DOM while it is not shown, for example while it loads or when it failed. |
| onLoadingStatusChange | (status) => void | — | Called with , , or whenever the loading status of the image changes. |
Initials or an icon, shown while the image loads or when there is none. The text size follows the avatar size.
| Prop | Type | Default | Description |
|---|---|---|---|
| delay | number | 0 | How long to wait before the fallback shows, in milliseconds. Use it so the initials do not flash while a fast image loads. |
A dot on the top right corner, centred on the circle's edge or the square's corner. A status sets a presence dot with a shape per status and an accessible name that defaults to the status.
| Prop | Type | Default | Description |
|---|---|---|---|
| status | "available" | "busy" | "away" | "dnd" | "offline" | "unknown" | — | The presence dot: , , , , or . Each has its own shape and an accessible name by default (, , , , , ). Without the badge is an empty dot for your own content. |
An avatar with a name and a second line, and optionally a capacity bar or a control at the end. It is a plain div. It replaces PersonCell and UserInfo, which still render the same row.
| Prop | Type | Default | Description |
|---|---|---|---|
| name required | string | — | The name, cut to one line. The initials are taken from it when there is no photo and no . Required. |
| subtext | ReactNode | — | The line under the name, such as a role or an email. |
| src | string | — | The address of a photo. It replaces the initials and has empty alternative text, because the name stands beside it. |
| initials | string | — | The text in the avatar without a photo. Default: the first letters of the first two words of the name. |
| color | "indigo" | "blue" | "purple" | "pink" | "red" | "orange" | "yellow" | "green" | "alternative" | "grey" | — | The tint behind the initials, as on Avatar. Without it the avatar is grey. |
| size | "default" | "lg" | "xl" | "default" | The avatar: 36 px, 40 px or 44 px. |
| compact | boolean | — | Smaller text, 12 px for the name and 11 px for the second line, with a semibold name. On by default when there is a capacity bar. |
| nameWeight | "medium" | "semibold" | — | The weight of the name: or . Default: semibold when compact, medium otherwise. |
| tight | boolean | true | Removes the 2 px between the name and the second line. |
| capacity | { value: number; label?: ReactNode } | — | A load bar under the text, as 0 to 100 and an optional such as 25h. It is a meter: green up to 80 %, yellow up to 100 %, red above. |
| trailing | ReactNode | — | A control at the end of the row, such as an IconButton that opens a menu. |
| className | string | — | Extra classes on the row. Use them for padding, corners and a width. |
| Prop | Type | Default | Description |
|---|---|---|---|
| person required | Person | — | |
| capacity | { value: number; label?: ReactNode } | — | Size=lg adds a capacity bar: value 0–100 and a label like "32h". |
| role | ReactNode | — |
| Prop | Type | Default | Description |
|---|---|---|---|
| name required | string | — | |
| color | "indigo" | "blue" | "purple" | "pink" | "red" | "orange" | "yellow" | "green" | "alternative" | "grey" | — | |
| initials | string | — | |
| onMenu | () => void | — | |
| src | string | — | |
| subtext | string | — | |
| variant | "person" | "sidebar" | "menu" | "person" | person (42px avatar, 14px name) · sidebar (40px, 12px, padded) · menu (adds a ⋮ button) |
Notes for AI
Give your coding assistant the Markdown reference instead of screenshots.
get_component("avatar")npx wunderui-cli add avatarThe full library index for assistants is at /llms.txt.