Avatar
A compact visual identity element that shows an image, initials, or fallback content.
API Reference
Original primitive API
Behavior, accessibility details, and low-level props are documented by Base UI.
Basic
import { Avatar, AvatarImage, AvatarFallback } from "moduix";export function AvatarDemo() { return ( <Avatar> <AvatarImage src={avatarImage} alt="Alex T." /> <AvatarFallback delay={600}>LT</AvatarFallback> </Avatar> );}const avatarImage = "https://images.unsplash.com/photo-1543610892-0b1f7e6d8ac1?w=128&h=128&dpr=2&q=80";Full list of component variables available for project-level overrides.
| Property | Default | Description |
|---|---|---|
| --avatar-bg | var(--color-muted) | Controls avatar background color. |
| --avatar-color | var(--color-foreground) | Controls avatar text color. |
| --avatar-fallback-bg | var(--avatar-bg) | Controls fallback background color independently from the root. |
| --avatar-fallback-color | inherit | Controls fallback text and icon color. |
| --avatar-fallback-padding | 0 | Controls fallback inner padding. |
| --avatar-font-size | var(--avatar-font-size-md) | Controls avatar text font size. |
| --avatar-font-size-xs | var(--text-xs) | Controls avatar text font size for `xs` size. |
| --avatar-font-size-sm | var(--text-sm) | Controls avatar text font size for `sm` size. |
| --avatar-font-size-md | var(--text-md) | Controls avatar text font size for `md` size. |
| --avatar-font-size-lg | var(--text-lg) | Controls avatar text font size for `lg` size. |
| --avatar-font-size-xl | var(--text-lg) | Controls avatar text font size for `xl` size. |
| --avatar-font-weight | var(--weight-medium) | Controls avatar text font weight. |
| --avatar-image-object-fit | cover | Controls how the image fits into the avatar. |
| --avatar-image-object-position | center | Controls which part of the image remains visible when cropped. |
| --avatar-line-height | var(--avatar-line-height-md) | Controls avatar text line height. |
| --avatar-line-height-xs | var(--line-height-text-xs) | Controls avatar text line height for `xs` size. |
| --avatar-line-height-sm | var(--line-height-text-sm) | Controls avatar text line height for `sm` size. |
| --avatar-line-height-md | var(--line-height-text-md) | Controls avatar text line height for `md` size. |
| --avatar-line-height-lg | var(--line-height-text-lg) | Controls avatar text line height for `lg` size. |
| --avatar-line-height-xl | var(--line-height-text-lg) | Controls avatar text line height for `xl` size. |
| --avatar-radius | var(--radius-full) | Controls avatar corner radius. |
| --avatar-size | var(--avatar-size-md) | Controls avatar width and height. |
| --avatar-size-xs | var(--size-xs) | Controls the `xs` avatar size. |
| --avatar-size-sm | var(--size-sm) | Controls the `sm` avatar size. |
| --avatar-size-md | var(--size-md) | Controls the `md` avatar size. |
| --avatar-size-lg | var(--size-lg) | Controls the `lg` avatar size. |
| --avatar-size-xl | var(--size-xl) | Controls the `xl` avatar size. |
| --avatar-transition | var(--transition-default) | Controls image fade transition. |
Interactive variables scoped for docs preview without changing size scale tokens.
| Property | Value | Default | Description |
|---|---|---|---|
| --avatar-bg | var(--color-muted) | Controls avatar background color. | |
| --avatar-color | var(--color-foreground) | Controls avatar text color. | |
| --avatar-fallback-bg | var(--avatar-bg) | Controls fallback background color independently from the root. | |
| --avatar-fallback-color | inherit | Controls fallback text and icon color. | |
| --avatar-fallback-padding | 0 | Controls fallback inner padding. | |
| --avatar-image-object-fit | cover | Controls how the image fits into the avatar. | |
| --avatar-image-object-position | center | Controls which part of the image remains visible when cropped. | |
| --avatar-radius | var(--radius-full) | Controls avatar corner radius. |
Anatomy
Avatar is composed as one root with two content slots. Keep AvatarImage and AvatarFallback
inside the same Avatar so loading state, error state, and fallback timing stay synchronized.
Avatar
├─ AvatarImage
└─ AvatarFallback
└─ initials | icon | custom content<Avatar>
<AvatarImage src={avatarImage} alt="Alex T." />
<AvatarFallback delay={600}>LT</AvatarFallback>
</Avatar>| Part | Role |
|---|---|
Avatar | Root slot. Controls size, shape, inherited styles, and composition with render. |
AvatarImage | Image slot. Renders the visual identity when the src is loaded successfully. |
AvatarFallback | Fallback slot. Renders initials, icon, or custom content while loading or on image error. |
Avatar does not use service slots such as portal, backdrop, or viewport.
In most cases, keep default behavior and style visible slots with className and CSS variables.
Composition
Use className on Avatar, AvatarImage, and AvatarFallback. Like Base UI, each slot also
accepts state-based className and style functions plus render for element composition.
Use AvatarImage onLoadingStatusChange when application logic needs the image load state, and
AvatarFallback delay when you want to avoid a fallback flash during normal image loading.
Examples
Fallback Only
Render initials or short text directly inside AvatarFallback when no image is available. Use
the size prop to switch between the built-in xs, sm, md, lg, and xl sizes.
import { Avatar, AvatarFallback } from "moduix";export function AvatarFallbackOnlyDemo() { return ( <div className={styles.row}> {sizes.map((size) => ( <Avatar key={size} size={size}> <AvatarFallback>{size.toUpperCase()}</AvatarFallback> </Avatar> ))} </div> );}.row { display: flex; align-items: center; gap: var(--spacing-3);}const sizes = ["xs", "sm", "md", "lg", "xl"] as const;Render Composition
Avatar, AvatarImage, and AvatarFallback are all public slots. Use className on each
slot, and use Base UI's render prop when the root should compose with another element.
import { Avatar, AvatarImage, AvatarFallback } from "moduix";export function AvatarCompositionDemo() { return ( <Avatar render={<a href="mailto:alex@example.com" />} className={styles.compositionRoot}> <AvatarImage className={styles.compositionImage} src={avatarImage} alt="Alex T." /> <AvatarFallback className={styles.compositionFallback} delay={600}> LT </AvatarFallback> </Avatar> );}.compositionRoot { --avatar-size: var(--size-xl); text-decoration: none; transition: box-shadow var(--transition-default), transform var(--transition-default);}.compositionRoot:hover { box-shadow: 0 0 0 2px var(--color-background), 0 0 0 4px var(--color-primary); transform: translateY(-1px);}.compositionImage { object-position: 50% 35%;}.compositionFallback { --avatar-fallback-bg: var(--color-primary); --avatar-fallback-color: var(--color-primary-foreground);}const avatarImage = "https://images.unsplash.com/photo-1543610892-0b1f7e6d8ac1?w=128&h=128&dpr=2&q=80";Image Error
Keep a fallback in the composition so the avatar stays meaningful when the image fails to load.
import { Avatar, AvatarImage, AvatarFallback } from "moduix";export function AvatarImageErrorDemo() { return ( <Avatar> <AvatarImage src="https://example.com/does-not-exist.png" alt="Broken image example" /> <AvatarFallback>NA</AvatarFallback> </Avatar> );}Custom Styles
Pass className to the root, image, and fallback slots when styling with CSS Modules, Tailwind CSS, or CSS-in-JS.
import { Avatar, AvatarImage, AvatarFallback } from "moduix";export function CustomStylesAvatarDemo() { return ( <Avatar size="lg" className={styles.ring}> <AvatarImage className={styles.imageSaturated} src={avatarImage} alt="Alex T." /> <AvatarFallback className={styles.uppercase}>LT</AvatarFallback> </Avatar> );}.ring { box-shadow: 0 0 0 2px var(--color-background), 0 0 0 4px var(--color-ring);}.imageSaturated { filter: saturate(1.5);}.uppercase { text-transform: uppercase;}const avatarImage = "https://images.unsplash.com/photo-1543610892-0b1f7e6d8ac1?w=128&h=128&dpr=2&q=80";Fallback Icon
Pass any React node to AvatarFallback to use an icon from your application or icon library.
import { Avatar, AvatarFallback, ComputerIcon } from "moduix";export function AvatarCustomFallbackDemo() { return ( <Avatar size="lg" className={styles.customFallbackAvatar}> <AvatarFallback> <ComputerIcon className={styles.customFallbackIcon} /> </AvatarFallback> </Avatar> );}.customFallbackAvatar { --avatar-bg: var(--color-accent); --avatar-fallback-color: var(--color-accent-foreground);}.customFallbackIcon { width: 55%; height: 55%;}