Avatar
An image, an icon, or initials to represent a person.
Installation
pnpm dlx shadcn@latest add https://react-toolbox.io/r/avatar.jsonNew here? Set up your project first. Styles, fonts, and required components are included.
Usage
While an image loads or fails, the avatar shows children, an icon, or the first initial of title. Use fallbackDelay to avoid flashing the fallback on fast loads, and add an accessible label when the avatar conveys identity.
Composition
Compose groups and presence indicators around Avatar. Overflow members retain accessible names, and presence is announced as text as well as displayed with color.
pnpm dlx shadcn@latest add https://react-toolbox.io/r/example-recipes.json- AAda Lovelace
- GGrace Hopper
- MMargaret Hamilton
- +1Also Katherine Johnson
Show composition code
'use client';
import { AvatarGroupRecipe, AvatarStatusRecipe } from '@/components/ui/examples/recipes';
const people = [
{ id: 'ada', name: 'Ada Lovelace' },
{ id: 'grace', name: 'Grace Hopper' },
{ id: 'margaret', name: 'Margaret Hamilton' },
{ id: 'katherine', name: 'Katherine Johnson' },
];
export default function AvatarComposition() {
return (
<div className="flex flex-wrap items-center gap-8">
<AvatarGroupRecipe people={people} />
<AvatarStatusRecipe person={people[0]} status="online" />
</div>
);
}
API reference
Key props and defaults. Full types and inline documentation are included with the source in material/avatar.
Avatar
| Property | Type | Default |
|---|---|---|
alt | string | '' |
cover | boolean | false |
fallbackDelay | numberAvoid briefly flashing the fallback for cached or fast-loading images. | — |
image | ReactNodeURL images use automatic loading/fallback. Custom nodes own their loading and cover styling. | — |
onLoadingStatusChange | (status: 'idle' | 'loading' | 'loaded' | 'error') => void | — |
Material guidelines
- Use a consistent leading image to identify people or related content. The standard list avatar is 40px; align row text to the same keyline across the list.
- An avatar is presentational. If it opens a profile or menu, put it inside an accessible control with a 48px interaction area.