Avatar

People at a glance.

<sui-avatar><sui-persona>MiscStable

About

Initials or image for a person: the topbar, a table row, an activity feed. The brand marks everyone else and the accent, with accent, marks the signed-in user only; a failed image falls back to initials. For a name and a second line beside the avatar, use sui-persona.

Usage

<sui-avatar name="Dana Whitfield" size="md"></sui-avatar> <script type="module"> import { defineCustomElements } from "@shineui/core/loader"; import "@shineui/core/shineui.css"; defineCustomElements(); </script>

import { SuiAvatar } from "@shineui/react"; import "@shineui/core/shineui.css"; export function Example() { return <SuiAvatar name="Dana Whitfield" size="md" />; }

import { Component } from "@angular/core"; import { SuiAvatar } from "@shineui/angular"; @Component({ standalone: true, imports: [SuiAvatar], template: `<sui-avatar name="Dana Whitfield" size="md"></sui-avatar>`, }) export class Example { }

Basic

The avatar renders as role="img" named from name, so a screen reader reads the person, not the two letters. Initials are the first letter of the first two words of name; set initials yourself when that is not the pair you want.

<sui-avatar name="Dana Whitfield" size="md"></sui-avatar>

Sizes

xs 22, sm 26, md 32, lg 40 and xl 56 px. Initials scale at 36% of the box, so every size stays legible.

Tones and shape

Navy is everyone else; orange marks the signed-in user only. square swaps the circle for 8px corners, which suits an organization rather than a person.

Badge

badge puts a glyph on a disc at the corner: the kind of event on an inbox row, the way Linear marks a comment or a mention on the actor. badge-tone paints it from the status ladder or the brand and accent roles; neutral is the default. The disc is aria-hidden, so the row text has to say what happened.

Image and fallback

An image fills the box and its alt is empty, because the host already carries the name. A src that fails to load falls back to the initials instead of leaving a hole.

The second src is broken on purpose.

<div style="display:flex;flex-wrap:wrap;gap:12px;align-items:center"> <sui-avatar src="/docs/assets/imagery/manufacturing-160.webp" name="Kestrel Logistics" size="lg" square></sui-avatar> <sui-avatar src="/docs/assets/imagery/does-not-exist.jpg" name="Greg Cockerel" size="lg"></sui-avatar> <span style="font:460 12px/1.6 var(--font-sans);color:var(--ink-faint)">The second src is broken on purpose.</span> </div>

Persona

sui-persona is the avatar with a name and a second line beside it: the user row in a table, an activity feed or a topbar menu. meta is a faint right-aligned note, and inverse swaps to white ink for navy chrome such as the side nav footer.

The user-row patternsui-persona

Avatar, name and secondary line with an optional meta note at the end of the row.

Name weightsui-persona

weight sets the name from the type ramp: regular, medium, semibold, bold or heavy. Unset, the name is 640, a step under bold. In a list whose title is medium, weight="medium" keeps the assignee from outweighing the row; the second line and the meta note do not move.

Raise the gateway quota

Rotate the signing keys

Retire the legacy exporter

<div style="max-width:520px"> <div style="display:flex;align-items:center;justify-content:space-between;gap:16px;padding:10px 0;border-bottom:1px solid var(--hairline)"><span style="font-size:var(--text-md);font-weight:var(--w-medium);color:var(--ink)">Raise the gateway quota</span><sui-persona name="Dana Whitfield" size="xs" weight="medium"></sui-persona></div> <div style="display:flex;align-items:center;justify-content:space-between;gap:16px;padding:10px 0;border-bottom:1px solid var(--hairline)"><span style="font-size:var(--text-md);font-weight:var(--w-medium);color:var(--ink)">Rotate the signing keys</span><sui-persona name="Tom Gordon" size="xs" weight="medium"></sui-persona></div> <div style="display:flex;align-items:center;justify-content:space-between;gap:16px;padding:10px 0;border-bottom:1px solid var(--hairline);border-bottom:0"><span style="font-size:var(--text-md);font-weight:var(--w-medium);color:var(--ink)">Retire the legacy exporter</span><sui-persona name="Priya Natarajan" size="xs"></sui-persona></div> </div>

Inverse on navy chromesui-persona

The SideNav footer state.

API

`<sui-avatar>`

Properties

Property	Attribute	Type	Default	Description
`accent`	`accent`	`boolean`	`false`	The accent fill: the signed-in user.
`badge`	`badge`	`string`string \| undefined		Font Awesome class for a small glyph on a disc at the bottom-right corner: the kind of event on an inbox row's avatar, a comment or an assignment. The disc is 8px on xs, 10px on sm, 12px on md and 14px above, seated on the rim clear of the initials and ringed in the surface so it reads against the fill. It is aria-hidden: the row's own text carries the meaning.
`badgeTone`	`badge-tone`	`SuiAvatarBadgeTone`"accent" \| "attention" \| "brand" \| "critical" \| "info" \| "neutral" \| "positive"	`'neutral'`	Color role of the badge disc: `brand`, `accent`, or the status ladder `positive`, `info`, `attention`, `critical` and `neutral` (the default), painted from the same tokens as `sui-badge`. An unknown value paints neutral.
`initials`	`initials`	`string`string \| undefined		Explicit initials. Overrides the ones derived from `name`.
`name`	`name`	`string`string \| undefined		Full name. Drives the two-letter initials (the first letter of the first two words) and the accessible name, read through `role="img"`.
`size`	`size`	`SuiAvatarSize`"lg" \| "md" \| "sm" \| "xl" \| "xs"	`'md'`	Box size: xs 22px, sm 26px, md 32px, lg 40px, xl 56px. Initials scale at 36% of the box.
`square`	`square`	`boolean`	`false`	8px corners instead of a circle.
`src`	`src`	`string`string \| undefined		Image URL. Fills the box with an empty `alt`, since the host carries the name; falls back to initials when the image fails to load.

Types

`SuiAvatarBadgeTone` typeColor role of the corner badge: the two emphasis roles plus the shared status ladder.
No members.

`SuiAvatarSize` type
No members.

`<sui-persona>`

Properties

Property	Attribute	Type	Default	Description
`accent`	`accent`	`boolean`	`false`	Orange avatar: the signed-in user.
`initials`	`initials`	`string`string \| undefined		Explicit avatar initials.
`inverse`	`inverse`	`boolean`	`false`	Inks fitted for the brand fill (SideNav footer): `--brand-contrast` for the name and the contrast-mode muted rung for the second line, so dark mode clears 4.5:1.
`meta`	`meta`	`string`string \| undefined		Faint note at the end of the row (role, relative time).
`name`	`name`	`string`	`''`	Display name, also the avatar's initials source.
`secondary`	`secondary`	`string`string \| undefined		Second line: email, role, firm.
`size`	`size`	`SuiPersonaSize`"lg" \| "md" \| "sm" \| "xs"	`'md'`	Avatar size: xs 22px, sm 26px, md 32px, lg 40px.
`src`	`src`	`string`string \| undefined		Avatar image URL.
`weight`	`weight`	`SuiPersonaWeight`"bold" \| "heavy" \| "medium" \| "regular" \| "semibold" \| undefined		Weight of the name, one of the ramp's stops: `regular` 460, `medium` 550, `semibold` 620, `bold` 650, `heavy` 700. Unset, the name keeps its shipped 640, a step under bold. In a table whose title column is `medium`, set `medium` so an assignee does not outweigh the row's own title. The second line and the meta note keep their weights.

Types

`SuiPersonaSize` type
No members.

`SuiPersonaWeight` typeWeight of the name, from the type ramp.
No members.

Theming

Every design token this element can render with, read from its own stylesheets and the ones it imports. Set a token on :root or on any ancestor and every use below follows it. The values shown are the ones in the theme you are viewing. The list is read per stylesheet, so an element that imports a shared drawing module lists that module's tokens too, whether or not it paints with all of them.