Avatar shows an image with a first-letter fallback. Use it beside a record name or inside a Chip.
Image and fallback
-. 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.
icon takes precedence over both the image and the first-letter fallback. pulsing animates opacity and respects reduced-motion preferences.
Open a profile
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.