Skip to main content
Avatar shows an image with a first-letter fallback. Use it beside a record name or inside a Chip. Its default root is a presentational span.

Usage

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 default fallback are decorative. name supplies the visual initial and fallback colors without adding an accessible label. When the avatar is the only representation of a person or record, set imageProps={{ alt: name }} to label both the image and default fallback. Keep the avatar decorative when a visible name or labeled owner already provides that information. imageProps accepts the complete image contract, including srcSet, sizes, crossOrigin, referrerPolicy, native events, refs, and render. Its src overrides the shorthand src. fallbackProps accepts the complete fallback contract, including delay, children, labeling, refs, and render. A custom fallback render owns its accessibility semantics; set aria-hidden explicitly when it is decorative.

Compose the parts

Use Avatar.Root, Avatar.Image, and Avatar.Fallback when you own the anatomy. Root supplies the size, shape, and fallback appearance; it does not generate children or accessible labels.
The parts share Base UI’s image loading state. Image renders an img after a successful load by default, and Fallback renders a span while the image is absent, loading, or has failed. delay postpones the initial fallback display in milliseconds and defaults to 0. A changed source is loaded again and can replace either the current image or fallback. Avatar.Image exposes onLoadingStatusChange with idle, loading, loaded, and error status values. The callback runs when Base UI reports a non-idle status change; unmounting the Image part resets the shared root state to idle. Root, Image, and Fallback accept state-aware className, style, and render functions with imageLoadingStatus; Image also exposes transitionStatus. Use keepMounted on Image when the rendered image must load in place, including loading="lazy" or an optimized image component. Forward native attributes, events, and the ref from custom image renderers. A mounted image can still be loading or failed; inspect loading state rather than treating its presence as success. The front component renderer currently supports the default preload path with src. Its host image does not receive srcSet, sizes, loading, decoding, or referrerPolicy. A changing custom render function with keepMounted can leave a decoded image hidden because the worker cannot read its completion state or dimensions. Use default preloading there until those renderer capabilities are available. The public AvatarRootProps, AvatarImageProps, AvatarFallbackProps, AvatarRootState, AvatarImageState, AvatarFallbackState, and AvatarImageLoadingStatus types are exported from twenty-ui/primitives/data-display. Refs target the rendered DOM element: span, img, and span by default, or the element supplied through render.

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. The icon itself is decorative, so label the root when it conveys information. pulsing animates opacity and respects reduced-motion preferences.

Open a profile

Compose a native button for actions. It owns focus, Enter and Space activation, and disabled behavior. Supply an action-specific accessible name. Put onClick and disabled on the rendered button; shorthand Avatar has no onClick, disabled, or nativeButton prop. For navigation, compose an anchor with an href or a router link that preserves anchor semantics. Native links activate with Enter. Keep navigation and disabled behavior with the link or interactive component you compose.

Migrate clickable avatars

Compose a native button through render for actions, or an anchor or router link for navigation. Move onClick and disabled onto that owner and remove nativeButton. Give the owner a useful accessible name and avoid nesting interactive elements. Avatar.Root and the other explicit parts retain the complete Base UI event contract. Shorthand avatars are decorative by default. name does not name the image, fallback, or interactive owner. Use a nonempty imageProps.alt only when the avatar conveys identity that is not already supplied by visible text or an owner label. With explicit parts, supply image alternative text and fallback labels or decorative attributes yourself, and keep translated content in your application.

Props

Types and defaults are generated from the public component types. The explicit parts accept native attributes and event handlers. Shorthand Avatar omits onClick; supply it on the owner passed through render.
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.
AvatarFallbackProps
Complete Avatar.Fallback props, including caller-owned children, labeling, refs, render, and fallback delay in milliseconds.
ReactNode
Decorative icon rendered instead of the image and first-letter fallback. Give the root an accessible label when the icon conveys information.
AvatarImageProps
Complete Avatar.Image props, including native image attributes, refs, render, keepMounted, and onLoadingStatusChange. Alternative text defaults to an empty string. Supply a nonempty alt to label the image and default fallback.
string
Name used for the first-letter fallback and fallback colors. Does not add an accessible label.
boolean
default:"false"
Animates the avatar opacity. Respects reduced-motion preferences.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, AvatarRootState>
Caller-supplied root element or renderer. Defaults to a presentational span. Compose a native button or link explicitly for interaction, and put its click handler and disabled state on that owner.
boolean
default:"false"
Surrounds the avatar with a background-colored ring so overlapping avatars stay distinct.
"circle" | "rounded-square" | "square"
default:"square"
Shape of the avatar and its fallback.
"lg" | "md" | "sm" | "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. imageProps.src overrides this value.
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.

Avatar.Root

string
Background color override for a first-letter fallback.
string
Border color override for the outline fallback.
ReactNode
Caller-owned Image, Fallback, and other content.
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.
string
Name used to choose fallback colors. Does not add children or accessible labels.
boolean
default:"false"
Animates the avatar opacity. Respects reduced-motion preferences.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, AvatarRootState>
Caller-supplied root element or renderer. Defaults to a presentational span. Compose a native button or link explicitly for interaction, and put its click handler and disabled state on that owner.
boolean
default:"false"
Surrounds the avatar with a background-colored ring so overlapping avatars stay distinct.
"circle" | "rounded-square" | "square"
default:"square"
Shape of the avatar and its fallback.
"lg" | "md" | "sm" | "xl" | "xs"
default:"md"
Avatar size: xs (12px), sm (14px), md (16px), lg (24px), or xl (40px).
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.

Avatar.Image

string
Caller-owned alternative text. Use an empty string for decorative images.
string | ((state: AvatarImageState) => string | undefined)
CSS class applied to the element, or a function that returns a class based on the component’s state.
"" | "anonymous" | "use-credentials"
Native image cross-origin policy, also used during preloading.
boolean
default:"false"
Keeps the image mounted and loads it in place. Loading and failed images stay hidden while Fallback is shown.
"eager" | "lazy"
Native eager or lazy loading. Use keepMounted for lazy loading.
((status: ImageLoadingStatus) => void)
Called when Base UI reports a loading, loaded, or error status. Shares that state with Root and Fallback.
"" | "no-referrer-when-downgrade" | "no-referrer" | "origin-when-cross-origin" | "origin" | "same-origin" | "strict-origin-when-cross-origin" | "strict-origin" | "unsafe-url"
Native image referrer policy, also used during preloading.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<DetailedHTMLProps<ImgHTMLAttributes<HTMLImageElement>, HTMLImageElement>, AvatarImageState>
Replaces the image. Preserve a native image and forward the supplied attributes, events, and ref.
string
Native responsive image sizes used with srcSet.
string
Image URL. Image renders after a successful load unless keepMounted is enabled.
string
Native responsive image source candidates.
CSSProperties | ((state: AvatarImageState) => CSSProperties | undefined)
Style applied to the element, or a function that returns a style object based on the component’s state.

Avatar.Fallback

ReactNode
Caller-owned fallback content, such as initials or an icon.
string | ((state: AvatarFallbackState) => string | undefined)
CSS class applied to the element, or a function that returns a class based on the component’s state.
number
default:"0"
Milliseconds before the initial fallback is shown. Defaults to 0.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, AvatarFallbackState>
Replaces the fallback span. Forward the supplied props and ref, and provide its accessible label or decorative attributes.
CSSProperties | ((state: AvatarFallbackState) => CSSProperties | undefined)
Style applied to the element, or a function that returns a style object based on the component’s state.