Avatar
React avatar with image, initials fallback, sizes, shapes, status dot, and stacked groups with +N overflow. Accessible names built in.
Avatar shows a photo, and AvatarFallback shows initials when the image is missing. Use AvatarGroup to stack several with a "+N" overflow.
When to use
Use Avatar to represent a person or an organization in headers, comments, timelines, and tables. Provide AvatarFallback initials for missing photos.
Use AvatarGroup to show several participants compactly, and keep the group capped so it stays readable.
Examples
Props
Props declared by Avatar. Native attributes of the underlying element pass through.
<Avatar>
| Prop | Type | Default | Description |
|---|---|---|---|
size | "sm" | "md" | "lg" | "xs" | "xl" | "2xl" | "3xl" | ||
shape | "circle" | "square" | ||
status | AvatarStatus | Presence indicator rendered in the bottom-{end} corner. The color tracks the status (online → success, busy → destructive, away → warning, offline → muted). Position flips in RTL automatically via logical props. | |
statusLabel | string | Accessible label for the status indicator. Defaults to the status value (e.g. "online"). Pass a localized string for non-English UIs. | |
asChild | boolean |
<AvatarImage>
| Prop | Type | Default | Description |
|---|---|---|---|
onLoadingStatusChange | (status: ImageLoadingStatus) => void | ||
asChild | boolean |
<AvatarFallback>
| Prop | Type | Default | Description |
|---|---|---|---|
colorScheme | "primary" | "secondary" | "destructive" | "default" | "success" | "warning" | "info" | ||
delayMs | number | ||
asChild | boolean |
<AvatarGroup>
| Prop | Type | Default | Description |
|---|---|---|---|
max | number | Cap the number of visible Avatars. Excess children are collapsed into a trailing "+N" chip. When unset, every child is rendered. | |
size | "sm" | "md" | "lg" | "xs" | "xl" | "2xl" | "3xl" | Size cascaded to each child Avatar that doesn't already set its own size. | |
shape | "circle" | "square" | Shape cascaded to each child Avatar that doesn't already set its own shape. | |
overflowLabel | (count: number) => string | Accessible label for the "+N" overflow chip. Defaults to "N more" - pass a
localized builder for non-English UIs. |
Accessibility
Avatar exposes role="img" with an accessible name from the alt or fallback text. The status dot is decorative, so state the status in text nearby when it matters.
Groups announce the overflow count as text rather than only showing "+N" visually.