DocsComponents

Avatar

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

person

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

Use image for a picture, icon for a Material Icon, or children for initials. A title displays its first initial. Add an accessible label when the avatar conveys identity.

Use the Code tab above for a complete example. The import follows your configured UI alias. See Theming to customize colors, spacing, and style slots.

State and callbacks

Avatar renders the supplied image, icon, title, or children. It has no controlled or uncontrolled selection state.

API reference

Generated from the installed TypeScript source. Defaults are the values declared by each function; a dash means no parameter default is declared. Forwarded props can use the receiving component’s default. Callback types show the exact arguments passed to your handler.

`Avatar`

Property	Type	Default
`alt`	`string`	`''`
`cover`	`boolean`	`false`
`icon`	`ReactNode`	`—`
`image`	`ReactNode`	`—`
`classNames`	`AvatarTheme` Classes for the component's rendered parts. Applied after legacy theme overrides.	`—`
`theme`Deprecated alias	`AvatarTheme` Use classNames for style slots; use ThemeProvider for design tokens.	`—`

Also inherits ComponentPropsWithRef<'div'>, except the omissions and overrides in its exported props type below. Use the supported native aria-*, data-*, event, and element attributes as appropriate.

Style slots

Pass a map of Tailwind classes to classNames. Available keys:

avatar
image
letter

theme is the deprecated compatibility alias. When both are provided, classNames wins conflicting utilities within each slot. See Theming for tokens and override rules.

Exported TypeScript types

Expand a type to inspect its full declaration, including generic constraints, union branches, callback arguments, ref handles, and inherited props. Import these types from @/components/ui/material/avatar.

AvatarProps

tsx

interface AvatarProps extends ComponentPropsWithRef<'div'> {
  alt?: string;
  cover?: boolean;
  icon?: ReactNode;
  image?: ReactNode;
  /** Classes for the component's rendered parts. Applied after legacy theme overrides. */
  classNames?: AvatarTheme;
  /** @deprecated Use classNames for style slots; use ThemeProvider for design tokens. */
  theme?: AvatarTheme;
}

AvatarTheme

tsx

type AvatarTheme = Partial<Record<'avatar' | 'image' | 'letter', string>>;

AvatarClassNames

tsx

type AvatarClassNames = AvatarTheme;

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