Skip to content

Avatar

An image, an icon, or initials to represent a person.

JC

Installation

Terminal
pnpm dlx shadcn@latest add https://react-toolbox.io/r/avatar.json

New 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.

Terminal
pnpm dlx shadcn@latest add https://react-toolbox.io/r/example-recipes.json
  • Ada Lovelace
  • Grace Hopper
  • Margaret Hamilton
  • Also Katherine Johnson
Show composition code
tsx
'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 number

Avoid briefly flashing the fallback for cached or fast-loading images.

—
image ReactNode

URL 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.

Material Design 1: Lists