Avatar
An avatar component with image loading states, skeleton and fallback support
Installation
Usage
Basic Usage
Avatar component handling image loading, success, and failure states with skeleton and fallback.
"use client";
import { Avatar } from "@/ui";
export default function AvatarDemo() {
return (
<div className="flex gap-4 items-center">
<Avatar src="https://picsum.photos/seed/av1/200/200" alt="user avatar" />
<Avatar
alt="broken avatar"
skeleton={<div className="bg-neutral animate-pulse size-full" />}
fallback={
<div className="flex items-center justify-center bg-neutral text-background size-full font-bold">
US
</div>
}
/>
</div>
);
}
Custom
Compose AvatarRoot and AvatarImage directly. They carry the same default styles as the composite Avatar and can be freely assembled and overridden via className.
"use client";
import { AvatarRoot, AvatarImage } from "@/ui";
export default function AvatarAtomicDemo() {
return (
<AvatarRoot className="w-14 h-14 rounded-full bg-muted overflow-hidden">
<AvatarImage
src="https://picsum.photos/seed/av1/200/200"
alt="user avatar"
className="object-cover"
/>
</AvatarRoot>
);
}
API Reference
High-level Components
Ready-to-use composite components.
Avatar
A self-managing avatar component that preloads the image and switches between skeleton, image, and fallback states.
| Prop | Type | Default | Description |
|---|---|---|---|
src | string | - | Image source URL, required |
skeleton | React.ReactNode | - | Content shown while the image is loading |
fallback | React.ReactNode | - | Content shown when the image fails to load |
className | ClassNameValue | - | Custom classes, applied to the root container |
style | React.CSSProperties | - | Inline styles, applied to the root container |
classNames | { image?: ClassNameValue } | - | Custom classes for the image |
styles | { image?: React.CSSProperties } | - | Inline styles for the image |
Supports all native <img> attributes (such as alt); className and style apply to the root container.
Composable Components
AvatarRoot
The container element rendered as a square with default size-12, centered content and hidden overflow.
| Prop | Type | Default | Description |
|---|---|---|---|
className | ClassNameValue | - | Custom CSS class |
Supports all native <div> attributes.
AvatarImage
The image element rendered with lazy loading and async decoding.
| Prop | Type | Default | Description |
|---|---|---|---|
src | string | - | Image source URL, required |
className | ClassNameValue | - | Custom CSS class |
Supports all native <img> attributes.