Skip to content

Design system

Documentation

DesignComponents / Avatar

Components / Avatar

Beta

Avatar

Show a named image, a readable fallback, and optional status in a compact footprint.

On this page

Examples

Image fallback, status, and group

Provide an accessible name, readable initials when no image is available, and text status for people who need it.

+2

Avatar initials, status indicators, and grouped overflow

Try the props

Compare size and the accessible status included in the avatar name.

Avatar property playground

When to use

Use Avatar to identify a person or named item in a list, card, or compact summary. The component renders a supplied image URL but does not fetch profile data. Provide initials or a useful fallback for image failures.

Usage

import { Avatar, AvatarGroup } from "@phuctech/ui/components/avatar";

<Avatar alt="Ava Nguyen" src={photoUrl} initials="AN" status="online" />
<AvatarGroup label="Project members" max={3}>{members}</AvatarGroup>

API

Component API
PropTypeDefaultDescriptionConstraints
altstringrequiredAccessible name for the person or item.Do not include redundant words such as image or avatar.
src / imageProps / onImageErrorstring / ImgHTMLAttributes / event handler—Optional image URL and native image settings; image errors switch to fallback and call both error handlers.The component does not request remote metadata.
initials / fallbackstring / ReactNodefirst character of altContent shown when there is no usable image.fallback takes precedence over initials.
size / shape"sm" | "md" | "lg" / "circle" | "rounded""md" / "circle"Shared size and silhouette choices.Keep identity labels readable at the selected size.
status / statusLabel"online" | "busy" | "away" | "offline" / string—Adds a semantic dot and includes status text in the accessible name.Do not rely on dot color alone.
AvatarGroup label / maxstring / number"People" / allNames the group and optionally limits visible children with a remainder indicator.Provide avatars as children; group does not fetch or reorder them.

Tokens

Component tokens
TokenRoleEffective valueUsage
muted / muted-foregroundFallback surface and textSemantic surface pairKeeps initials readable in both themes.
success / danger / warningStatus indicatorSemantic status colorsThe status is also included in the accessible name.

Accessibility

The root exposes the supplied alt text as its accessible name; a status is appended when present. The image itself is decorative to prevent duplicate announcements, and fallback text is hidden from assistive technology. AvatarGroup is a labeled group; overflow announces the number of additional people.

Do and don’t

Do

Supply a meaningful name and a stable fallback for missing or failed images.

Don’t

Use color-only status or rely on initials to distinguish people with the same name.

  • Badge labels an entity with a short status or category.
  • Tooltip can add optional context to an adjacent control.