Default
Show the codeHide the code
Default, code
<Avatar name="Priya Shah" />Avatar
Initials on a brand tint for a person or team; AvatarGroup stacks several with a count.
- Free core, MIT
- Version 2.0.0-rc.1
- APG pattern: img
Examples
These are the real React components. Use them with a mouse, touch or keyboard, and switch the theme and density for every example at once.
Sizes
Show the codeHide the code
Sizes, code
<div className="flex items-center gap-gap-md"><Avatar name="Priya Shah" size="sm" /><Avatar name="Tom Ellis" /><Avatar name="Ana Costa" size="lg" /></div>Beside a visible name
Kofi Mensah
Show the codeHide the code
Beside a visible name, code
<div className="flex items-center gap-gap-sm text-body-md text-fg"><Avatar name="Kofi Mensah" decorative /><span>Kofi Mensah</span></div>Group
Show the codeHide the code
Group, code
<AvatarGroup label="Project members" names={['Priya Shah', 'Tom Ellis', 'Ana Costa', 'Kofi Mensah', 'Li Wei', 'Sam Okoro']} />All sizes
Show the codeHide the code
All sizes, code
<div className="flex items-center gap-gap-md">{(['xs', 'sm', 'md', 'lg', 'xl'] as const).map((sz) => <Avatar key={sz} name="Priya Shah" size={sz} />)}</div>Presence
Show the codeHide the code
Presence, code
<div className="flex items-center gap-gap-md">{(['online', 'away', 'busy', 'offline'] as const).map((p) => <Avatar key={p} name="Tom Ellis" presence={p} size="lg" />)}</div>Tints
Show the codeHide the code
Tints, code
<div className="flex flex-wrap items-center gap-gap-md">{avatarTints.map((t) => <Avatar key={t} name={`${t} tint`} tint={t} />)}</div>Tokens
The 23 design tokens Avatar reads, with the value each has in the theme and density chosen above. Change a token and the component follows, in Figma and in code.
Show all 23 tokens
| Token | Value now | CSS variable |
|---|---|---|
| avatar.stack-overlap | … | --sd-avatar-stack-overlap |
| avatar.stack-overlap-sm | … | --sd-avatar-stack-overlap-sm |
| avatar.stack-ring | … | --sd-avatar-stack-ring |
| avatar.tint.1.bg | … | --sd-avatar-tint-1-bg |
| avatar.tint.1.fg | … | --sd-avatar-tint-1-fg |
| avatar.tint.2.bg | … | --sd-avatar-tint-2-bg |
| avatar.tint.2.fg | … | --sd-avatar-tint-2-fg |
| avatar.tint.3.bg | … | --sd-avatar-tint-3-bg |
| avatar.tint.3.fg | … | --sd-avatar-tint-3-fg |
| avatar.tint.4.bg | … | --sd-avatar-tint-4-bg |
| avatar.tint.4.fg | … | --sd-avatar-tint-4-fg |
| avatar.tint.5.bg | … | --sd-avatar-tint-5-bg |
| avatar.tint.5.fg | … | --sd-avatar-tint-5-fg |
| avatar.tint.6.bg | … | --sd-avatar-tint-6-bg |
| avatar.tint.6.fg | … | --sd-avatar-tint-6-fg |
| color.bg.canvas | … | --sd-color-bg-canvas |
| color.bg.muted | … | --sd-color-bg-muted |
| color.icon.danger | … | --sd-color-icon-danger |
| color.icon.default | … | --sd-color-icon-default |
| color.icon.success | … | --sd-color-icon-success |
| color.icon.warning | … | --sd-color-icon-warning |
| color.text.default | … | --sd-color-text-default |
| radius.full | … | --sd-radius-full |
Install
The npm package isn’t published yet. When it is, this is the install line; until then, this page runs the same build of the package (from commit fa3abf8).
Install
npm i @superduperui/react @superduperui/tokensImport
import { Avatar, AvatarGroup, initialsOf, tintFor, avatarTints } from "@superduperui/react"Props
Avatar also takes the props of the React Aria component it’s built on.
| Prop | Type | What it does |
|---|---|---|
namerequired | string | The person's or team's name. Becomes the accessible name unless `decorative`. |
decorative | booleanDefault false | Set when the name is already visible next to the avatar (then it is hidden from screen readers). |
size | 'xs' | 'sm' | 'md' | 'lg' | 'xl'Default 'md' | xs 24px, sm 32px, md 40px (default), lg 48px, xl 64px. |
tint | AvatarTint | 'auto'Default 'auto' | Decorative tint 1 to 6. "auto" (default) picks one from the name, the same every time. |
presence | 'online' | 'away' | 'busy' | 'offline' | Presence dot: online (filled), away (ring), busy (filled with a bar), offline (hollow). Added to the accessible name. |
When to use it
Use it for
- Member lists, comments, assignees
- Account menus
Use something else for
- Photos of real people in the system files (licence): products add uploads themselves
- A button: wrap Avatar in a Button with a name
Accessibility
Screen readers announce "Priya Shah, image"; a group "Project members: Priya Shah, Tom Ellis, image".
WCAG 2.2 AAA criteria the component meets in Comfortable density: 1.4.6, 1.4.9, 2.3.2.
Not interactive: density changes spacing only.
What your product still has to do
- Use decorative when the name is visible next to it
- Name every AvatarGroup with label
This release’s test results
| axe-core (WCAG A, AA, AAA and best practice) | 160 runs across every story, theme, density and width: 0 violations |
|---|---|
| Rendered text contrast | 485 text runs: 0 below 7:1, lowest 9.8:1 |
| Target size | 0 targets: 0 under 44px in Comfortable |
| Focus appearance (2.4.13) | 0 focus stops in 0 browser engines: all pass |
Manual passes with VoiceOver and NVDA haven’t been done yet.
In Figma
The Figma component is Avatar, with Size (Small, Medium, Large, X-small, X-large); Tint (1, 2, 3, 4, 5, 6, Auto); Presence (None, Online, Away, Busy, Offline). The Figma library isn’t published yet.
Figma to code: Size → size (Small = "sm", Medium = "md", Large = "lg", X-small = "xs", X-large = "xl"); Initials → name (initials are generated); Tint → tint (1 = 1, 2 = 2, 3 = 3, 4 = 4, 5 = 5, 6 = 6, Auto = "auto"); Presence → presence (None, Online = "online", Away = "away", Busy = "busy", Offline = "offline").