API and Development
Avatar represents people and entities across the product. It supports images and text fallback.
Pass exactly one of alt (accessible description) or decorative (skips the avatar for screen readers, e.g. when an adjacent name already announces it) — passing both, or neither, is a type error.
| Name | Type | Default | Description |
|---|---|---|---|
alt | AvatarName | — | Accessible name, such as the person's name. The first character is the default initials. Not allowed on a decorative avatar. |
color | AvatarColor | — | Fill and initials color. Defaults to {@link AvatarColor.Default}. |
decorative | boolean | — | When omitted or false, the avatar is meaningful and must supply alt.
Hides the avatar from assistive technology. |
fallback | AvatarName | — | Text shown when there is no image. Defaults to the first character of alt. |
id | string | — | Element id of the root. |
ref | Ref<HTMLSpanElement> | — | Ref to the root span. |
shape | AvatarShape | — | Outline. Defaults to {@link AvatarShape.Circle}. |
size | AvatarSize | — | Diameter and initials type role. Defaults to {@link AvatarSize.Regular}. |
src | string | — | Trusted image URL, rendered with Image. Without it, or when it fails to load, the initials show. |
Avatar supports three sizes for different layout needs—Small, Regular, and Large.
Small in compact layouts, such as lists or dense UIs.
Default is suitable for most contexts.
Large when the avatar is a focal point, such as profile views.
Color variants help convey emphasis or state.
Default is standard color for most use cases.
Accent for active, live, or otherwise emphasized avatars.
Choose a shape that matches the context.
Cicle, is appropriate for people avatars.
Square for organizations or when a more structured look is desired.
Avatar adapts based on the data provided.
Image displays a profile image when src is provided.
alt when no image is available.
fallback content for greater control.
decorative when the name already appears as visible text next to the avatar, so it isn't announced twice.