Skip to main content
Avatar shows an image with a first-letter fallback. Use it beside a record name or inside a Chip.

Image and fallback

When the image is absent or fails to load, the fallback shows the first letter of the trimmed name in uppercase. An empty name shows -. colorSeed chooses stable fallback colors and defaults to name; use a record identifier to keep the color stable when the name changes. The image and fallback are decorative. Keep the visible name beside the avatar, as above. For a standalone avatar that conveys information, supply role="img" and an aria-label.

Shape and appearance

shape accepts square, rounded-square, or circle. Sizes run from xs (12px) to xl (40px); md is 16px. variant="outline" adds a border to the fallback. The color, backgroundColor, and borderColor overrides customize the fallback, while a loaded image keeps its original appearance.
An icon takes precedence over both the image and the first-letter fallback. pulsing animates opacity and respects reduced-motion preferences.

Open a profile

Supplying onClick renders a button with pointer, Enter, and Space activation. Use disabled to prevent activation. The default accessible name comes from name, but an action-specific aria-label makes the purpose clearer. When replacing the button through render, set nativeButton={false} for a non-button element.

Props

Types and defaults are generated from the public component types. Native attributes and event handlers are also accepted.
string
Background color override for a first-letter fallback.
string
Border color override for the outline fallback.
string | ((state: AvatarRootState) => string | undefined)
CSS class applied to the element, or a function that returns a class based on the component’s state.
string
Text color override for a first-letter fallback.
string
Stable value used to choose fallback colors. Defaults to name.
boolean
default:"false"
Applies disabled styling and disables activation when onClick is supplied.
ReactNode
Icon rendered instead of the image and first-letter fallback.
string
Name used for the first-letter fallback and the default accessible name when clickable.
boolean
default:"true"
Set to false when a clickable avatar uses render with an element other than a native button.
boolean
default:"false"
Animates the avatar opacity. Respects reduced-motion preferences.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, AvatarRootState>
Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.
"circle" | "square" | "rounded-square"
default:"square"
Shape of the avatar and its fallback.
"sm" | "md" | "lg" | "xl" | "xs"
default:"md"
Avatar size: xs (12px), sm (14px), md (16px), lg (24px), or xl (40px).
string | null
Image URL. A missing or failed image shows the fallback.
CSSProperties | ((state: AvatarRootState) => CSSProperties | undefined)
Style applied to the element, or a function that returns a style object based on the component’s state.
"outline" | "soft"
default:"soft"
Visual treatment of the fallback.