Content & Data
Avatar
Avatar is a circular visual identity for a user or entity with image, initials, or icon fallback.
Size (Small/Medium/Large) — 3 variants
betaReact AvailableFigma AvailableDocs Partial
- React last updated
- 2026-07-13
- Documentation last updated
- 2026-06-01
- Accessibility target
- WCAG 2.2 AA (target)
- Version
- 0.5.0-beta
Known open questions
- Avatar Group overflow behavior is not confirmed — deferred.
- Status indicator ring on Avatar is not confirmed in Figma.
Live preview
Circular identity with image and fallbacks.
Image / initials / icon
Sizes
Decorative vs informative
Adjacent visible name
Usman Farooqi
Broken image fallback
Use empty alt and decorative when a visible name is adjacent. Provide label or meaningful alt when Avatar is the sole identification.
Purpose
A circular visual representation of a user or entity, showing initials as a fallback when no profile image is available.
Anatomy
Avatar = circular frame + image OR initials OR icon fallback.
Variants and states
image · initials · icon
When to use
Anywhere a user/account needs visual identification.
When not to use
Representing non-user entities better served by a different icon or logo mark.
Accessibility
If purely decorative alongside a visible name, mark aria-hidden; if it's the only identification, needs an accessible name.
Common mistakes
Using ambiguous or non-unique initials with no fallback plan.
Properties
Size as variants. Initials (text).
When should Avatar use empty alt text?
When the person’s name is visible adjacent to the Avatar and the image is decorative. Use meaningful alt or label when Avatar is the sole identification.
How should initials be announced?
Initials alone are not sufficient when a full legal name is required. Provide label for informative contexts; hide decorative avatars from assistive technology.
What happens when the Avatar image fails?
The component falls back to initials when provided, otherwise to the icon fallback — no broken-image UI.
Tokens used
semantic/action/primarysemantic/text/inverseradius/full
Component API
| Prop | Type | Default | Description |
|---|---|---|---|
| size | "sm" | "md" | "lg" | "md" | Confirmed Figma sizes. |
| src | string | — | Image source URL. |
| alt | string | — | Image alternative text when informative. |
| initials | string | — | Fallback initials when image unavailable. |
| label | string | — | Accessible name for initials/icon fallback. |
| decorative | boolean | false | Hides identity from assistive technology. |
React example
Copy React example
import { Avatar } from "@/components/ui/Avatar";
export function Example() {
return (
<div className="flex items-center gap-2">
<Avatar src="/avatar.jpg" alt="" decorative />
<span>Usman Farooqi</span>
</div>
);
}