Root Props
| Prop | Type | Default |
|---|---|---|
ref | Ref<HTMLDivElement> | — |
Ref forwarded to the root div element of the avatar. Enables access to the DOM node, e.g., for focus or measurements. | ||
size | AvatarSize | 'md' |
| Defines the size of the avatar. Affects both the container and any nested content (image, initials, etc.). | ||
variant | AvatarVariant | 'primary' |
| Visual variant of the avatar. Can be used to differentiate between roles, types, or contexts. 'primary': Default visual style; 'secondary': Alternate or less prominent style | ||
Also accepts all <div> attributes.
Child Parts
AvatarImage: image content.AvatarFallback: text fallback.AvatarIcon: icon fallback.
AvatarIcon
| Prop | Type | Default |
|---|---|---|
size | IconSize | — |
| Predefined size token for the icon. Can be overridden by explicit width and height. | ||
ref | Ref<SVGSVGElement> | — |
| Ref to the SVG element | ||
strokeWidth | number | — |
| Stroke thickness for SVG lines and shapes (in px or pt). | ||
children | ReactNode | — |
Icon content (required). Accepts: icons from ~/icons; custom inline SVG; third-party icon components (e.g. Lucide, Tabler) | ||
Also accepts all HTML attributes.
AvatarFallback
| Prop | Type | Default |
|---|---|---|
size | TextSize | — |
| Visual size of the text, typically mapped to the design system’s type scale. | ||
asChild | boolean | — |
If true, renders the text as a child component using Slot. Useful for compatibility with native elements or other components. | ||
fontWeight | 400 | 500 | 600 | 700 | 900 | — |
| Font weight applied to the text. Common values: 400: Regular; 500: Medium; 600: Semi-bold; 700: Bold; 900: Extra bold | ||
ref | Ref<HTMLSpanElement> | — |
Ref to the underlying <span> or slotted element. Useful for measuring, focusing, or DOM manipulation. | ||
Also accepts all <span> attributes.
AvatarImage
| Prop | Type | Default |
|---|---|---|
ref | Ref<HTMLImageElement> | — |
Ref to the native <img> element. Useful for direct DOM access, loading state tracking, or animations. | ||
fallbackSrc | string | — |
| URL of the fallback image to display if the main image fails to load. This allows graceful degradation of the avatar when the primary source is unavailable. | ||
Also accepts all <img> attributes.
Types
AvatarPropsAvatarImagePropsAvatarFallbackPropsAvatarIconPropsAvatarSizeAvatarVariant
State Model
Avataris stateless from the component API perspective.- Consumer content determines whether image, fallback, or icon is shown.