Avatar

Avatar — a person, as a photo or two initials.

Beta · Content blocks · packages/css/src/components/avatar.css · React on Base UI: @pepperui/avatar

.pui-avatar · size --24 --28 --40 --96 (36 default) · tone --blue --red --yellow · --square. A user glyph on sunken until a photo replaces it.

Avatar — every size and every stateOpen in the workshop

Sizes across, states down.

What it is for

Size: 24 (table rows), 28 (the nav pill), 36 (the shell), 40 (cards, comments), 96 (the user space); initials 12 / 12 / 15 / 15 / 36 SemiBold
Content: photo — a Lucide user glyph on surface/sunken until an image fill replaces it — or initials in blue, red or yellow: avatar/{tone}, hue 200 on hue 600, a component token because it deviates from tint/* on purpose
Initials is a text property (two letters); the tone is assigned per person and never changes
No states: an avatar is not interactive by itself; the nav pill or the row it sits in is
The square avatar for chat is its own set below

Use when a person is shown — the current user in the shell, an author, a row’s owner, a chat participant (square).

Do not use when it is a company or a product (a logo, from the Icons & logos page); it is a decorative circle; there is no fallback text — an avatar without initials is a broken image.

Relates to Avatar - square, Sidebar (user card), Topbar, Table, Chat pattern, Badge (a status dot on an avatar comes later).

Anti-patterns a photo with no initials behind it · initials in the brand hue at 400 (too loud) · one person shown in two tones · a 96 avatar anywhere but the user space.

Keywords: avatar, user, profile, initials, photo, person

Figma — page Avatar: Avatar (20 variants) · Avatar - square (20 variants)

shadcn: avatar

The markup — copy this

The class, the parts, and nothing that is not in the package. The same block opens avatar.css.

<span class="pui-avatar pui-avatar--blue">FK</span>
<span class="pui-avatar pui-avatar--40"><img src="…" alt="the design lead"></span>
<span class="pui-avatar pui-avatar--square pui-avatar--yellow pui-avatar--24">AI</span>

The modifiers

	What it is	Note
Size	--24 · --28 · (none) 36 · --40 · --96	—
Content	(none) photo / glyph on sunken · --blue · --red · --yellow	—
Shape	(none) round · --square	—

Accessibility — measured, not assumed

Every number here is measured on the rendered component: contrast (npm run contrast:render), the focus ring (npm run focus) and the keyboard (npm run keyboard). The floors are principle 12’s.

Contrast

ink on ground	reads	floor	the matrix calls it
`#634e0f` on `#fdf3d3`	7.2	4.5	Yellow avatar initials (promised)	ok
`#5b0e0d` on `#f9d3d2`	10.09	4.5	Red avatar initials (promised)	ok
`#110e56` on `#d4d3f7`	11.84	4.5	Blue avatar initials (promised)	ok

3 distinct pair(s) rendered, 0 that axe calls a violation.

The focus ring

Nothing in this component takes focus.

Keyboard

Nothing in this component claims an ARIA role with a keyboard contract; its controls are ordinary ones and the browser already gives them their keys.

Tab order across the whole library is document order over 344 stops, and Shift+Tab is its exact reverse — no keyboard trap anywhere (WCAG 2.1.2).