Avatar

Identify a person or team with an image and fallback initials.

View component source ↗

Preview

Example

A minimal example to get started.

AJMKSY

Installation

Install this component and its dependencies in a project initialized with shadcn.

pnpm dlx shadcn@latest add https://ui.hyunjoon.net/r/avatar.json

Usage

This is the basic example. Use the Code tab above for the selected example. Adjust import aliases to match your project.

import { Avatar, AvatarFallback, AvatarGroup } from "@/components/ui/avatar";

export default function Example() {
  return (
    <AvatarGroup>
      <Avatar>
        <AvatarFallback>AJ</AvatarFallback>
      </Avatar>
      <Avatar>
        <AvatarFallback>MK</AvatarFallback>
      </Avatar>
      <Avatar>
        <AvatarFallback>SY</AvatarFallback>
      </Avatar>
    </AvatarGroup>
  );
}

API reference

Derived from the installed component types. Native DOM props are also supported where applicable. A dash means no explicit default is documented. Some props depend on the selected mode.

Avatar

Avatar properties
Prop	Type	Default	Description
`ref`	React.Ref<HTMLSpanElement> \| undefined React.Ref<HTMLSpanElement> \| undefined	`—`	Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref).
`id`	string \| undefined string \| undefined	`—`	Unique identifier used to associate labels and descriptions.
`children`	React.ReactNode React.ReactNode	`—`	Content rendered inside this component.
`onFocus`	((event: BaseUIEvent<React.FocusEvent<HTMLSpanElement, Element>>) => void) \| undefined ((event: BaseUIEvent<React.FocusEvent<HTMLSpanElement, Element>>) => void) \| undefined	`—`	Called when the control receives focus.
`onBlur`	((event: BaseUIEvent<React.FocusEvent<HTMLSpanElement, Element>>) => void) \| undefined ((event: BaseUIEvent<React.FocusEvent<HTMLSpanElement, Element>>) => void) \| undefined	`—`	Called when the control loses focus.
`onChange`	((event: BaseUIEvent<React.ChangeEvent<HTMLSpanElement, Element>>) => void) \| undefined ((event: BaseUIEvent<React.ChangeEvent<HTMLSpanElement, Element>>) => void) \| undefined	`—`	Called when the underlying form control changes; inspect the event for its value.
`onKeyDown`	((event: BaseUIEvent<React.KeyboardEvent<HTMLSpanElement>>) => void) \| undefined ((event: BaseUIEvent<React.KeyboardEvent<HTMLSpanElement>>) => void) \| undefined	`—`	Called when a key is pressed while this element is focused.
`onClick`	((event: BaseUIEvent<React.MouseEvent<HTMLSpanElement, MouseEvent>>) => void) \| undefined ((event: BaseUIEvent<React.MouseEvent<HTMLSpanElement, MouseEvent>>) => void) \| undefined	`—`	Called when the element is activated.
`className`	string \| ((state: AvatarRootState) => string \| undefined) \| undefined string \| ((state: AvatarRootState) => string \| undefined) \| undefined	`—`	CSS class applied to the element, or a function that returns a class based on the component's state.
`render`	React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn… React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, AvatarRootState> \| undefined	`—`	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
`style`	React.CSSProperties \| ((state: AvatarRootState) => React.CSSProperties \| undefined) \| unde… React.CSSProperties \| ((state: AvatarRootState) => React.CSSProperties \| undefined) \| undefined	`—`	Style applied to the element, or a function that returns a style object based on the component's state.
`size`	"default" \| "sm" \| "lg" \| undefined "default" \| "sm" \| "lg" \| undefined	`"default"`	Visual size of the component.

AvatarImage

AvatarImage properties
Prop	Type	Default	Description
`onLoadingStatusChange`	((status: ImageLoadingStatus) => void) \| undefined ((status: ImageLoadingStatus) => void) \| undefined	`—`	Callback fired when the loading status changes.
`ref`	React.Ref<HTMLImageElement> \| undefined React.Ref<HTMLImageElement> \| undefined	`—`	Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref).
`id`	string \| undefined string \| undefined	`—`	Unique identifier used to associate labels and descriptions.
`children`	React.ReactNode React.ReactNode	`—`	Content rendered inside this component.
`onFocus`	((event: BaseUIEvent<React.FocusEvent<HTMLImageElement, Element>>) => void) \| undefined ((event: BaseUIEvent<React.FocusEvent<HTMLImageElement, Element>>) => void) \| undefined	`—`	Called when the control receives focus.
`onBlur`	((event: BaseUIEvent<React.FocusEvent<HTMLImageElement, Element>>) => void) \| undefined ((event: BaseUIEvent<React.FocusEvent<HTMLImageElement, Element>>) => void) \| undefined	`—`	Called when the control loses focus.
`onChange`	((event: BaseUIEvent<React.ChangeEvent<HTMLImageElement, Element>>) => void) \| undefined ((event: BaseUIEvent<React.ChangeEvent<HTMLImageElement, Element>>) => void) \| undefined	`—`	Called when the underlying form control changes; inspect the event for its value.
`onKeyDown`	((event: BaseUIEvent<React.KeyboardEvent<HTMLImageElement>>) => void) \| undefined ((event: BaseUIEvent<React.KeyboardEvent<HTMLImageElement>>) => void) \| undefined	`—`	Called when a key is pressed while this element is focused.
`onClick`	((event: BaseUIEvent<React.MouseEvent<HTMLImageElement, MouseEvent>>) => void) \| undefined ((event: BaseUIEvent<React.MouseEvent<HTMLImageElement, MouseEvent>>) => void) \| undefined	`—`	Called when the element is activated.
`alt`	string \| undefined string \| undefined	`—`	Accessible text alternative for the image.
`src`	string \| undefined string \| undefined	`—`	URL of the displayed resource.
`className`	string \| ((state: AvatarImageState) => string \| undefined) \| undefined string \| ((state: AvatarImageState) => string \| undefined) \| undefined	`—`	CSS class applied to the element, or a function that returns a class based on the component's state.
`render`	React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn… React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, AvatarImageState> \| undefined	`—`	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
`style`	React.CSSProperties \| ((state: AvatarImageState) => React.CSSProperties \| undefined) \| und… React.CSSProperties \| ((state: AvatarImageState) => React.CSSProperties \| undefined) \| undefined	`—`	Style applied to the element, or a function that returns a style object based on the component's state.

AvatarFallback

AvatarFallback properties
Prop	Type	Default	Description
`delay`	number \| undefined number \| undefined	`—`	How long to wait before showing the fallback. Specified in milliseconds.
`ref`	React.Ref<HTMLSpanElement> \| undefined React.Ref<HTMLSpanElement> \| undefined	`—`	Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref).
`id`	string \| undefined string \| undefined	`—`	Unique identifier used to associate labels and descriptions.
`children`	React.ReactNode React.ReactNode	`—`	Content rendered inside this component.
`onFocus`	((event: BaseUIEvent<React.FocusEvent<HTMLSpanElement, Element>>) => void) \| undefined ((event: BaseUIEvent<React.FocusEvent<HTMLSpanElement, Element>>) => void) \| undefined	`—`	Called when the control receives focus.
`onBlur`	((event: BaseUIEvent<React.FocusEvent<HTMLSpanElement, Element>>) => void) \| undefined ((event: BaseUIEvent<React.FocusEvent<HTMLSpanElement, Element>>) => void) \| undefined	`—`	Called when the control loses focus.
`onChange`	((event: BaseUIEvent<React.ChangeEvent<HTMLSpanElement, Element>>) => void) \| undefined ((event: BaseUIEvent<React.ChangeEvent<HTMLSpanElement, Element>>) => void) \| undefined	`—`	Called when the underlying form control changes; inspect the event for its value.
`onKeyDown`	((event: BaseUIEvent<React.KeyboardEvent<HTMLSpanElement>>) => void) \| undefined ((event: BaseUIEvent<React.KeyboardEvent<HTMLSpanElement>>) => void) \| undefined	`—`	Called when a key is pressed while this element is focused.
`onClick`	((event: BaseUIEvent<React.MouseEvent<HTMLSpanElement, MouseEvent>>) => void) \| undefined ((event: BaseUIEvent<React.MouseEvent<HTMLSpanElement, MouseEvent>>) => void) \| undefined	`—`	Called when the element is activated.
`className`	string \| ((state: AvatarFallbackState) => string \| undefined) \| undefined string \| ((state: AvatarFallbackState) => string \| undefined) \| undefined	`—`	CSS class applied to the element, or a function that returns a class based on the component's state.
`render`	React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn… React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, AvatarFallbackState> \| undefined	`—`	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
`style`	React.CSSProperties \| ((state: AvatarFallbackState) => React.CSSProperties \| undefined) \| … React.CSSProperties \| ((state: AvatarFallbackState) => React.CSSProperties \| undefined) \| undefined	`—`	Style applied to the element, or a function that returns a style object based on the component's state.

AvatarGroup

AvatarGroup properties
Prop	Type	Default	Description
`ref`	React.Ref<HTMLDivElement> \| undefined React.Ref<HTMLDivElement> \| undefined	`—`	Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref).
`defaultChecked`	boolean \| undefined boolean \| undefined	`—`	Initial checked state for an uncontrolled control.
`defaultValue`	string \| number \| readonly string[] \| undefined string \| number \| readonly string[] \| undefined	`—`	Initial value for an uncontrolled component.
`className`	string \| undefined string \| undefined	`—`	Additional CSS classes merged with the component styles.
`id`	string \| undefined string \| undefined	`—`	Unique identifier used to associate labels and descriptions.
`children`	React.ReactNode React.ReactNode	`—`	Content rendered inside this component.
`onFocus`	React.FocusEventHandler<HTMLDivElement> \| undefined React.FocusEventHandler<HTMLDivElement> \| undefined	`—`	Called when the control receives focus.
`onBlur`	React.FocusEventHandler<HTMLDivElement> \| undefined React.FocusEventHandler<HTMLDivElement> \| undefined	`—`	Called when the control loses focus.
`onChange`	React.ChangeEventHandler<HTMLDivElement, Element> \| undefined React.ChangeEventHandler<HTMLDivElement, Element> \| undefined	`—`	Called when the underlying form control changes; inspect the event for its value.
`onKeyDown`	React.KeyboardEventHandler<HTMLDivElement> \| undefined React.KeyboardEventHandler<HTMLDivElement> \| undefined	`—`	Called when a key is pressed while this element is focused.
`onClick`	React.MouseEventHandler<HTMLDivElement> \| undefined React.MouseEventHandler<HTMLDivElement> \| undefined	`—`	Called when the element is activated.

AvatarGroupCount

AvatarGroupCount properties
Prop	Type	Default	Description
`ref`	React.Ref<HTMLDivElement> \| undefined React.Ref<HTMLDivElement> \| undefined	`—`	Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref).
`defaultChecked`	boolean \| undefined boolean \| undefined	`—`	Initial checked state for an uncontrolled control.
`defaultValue`	string \| number \| readonly string[] \| undefined string \| number \| readonly string[] \| undefined	`—`	Initial value for an uncontrolled component.
`className`	string \| undefined string \| undefined	`—`	Additional CSS classes merged with the component styles.
`id`	string \| undefined string \| undefined	`—`	Unique identifier used to associate labels and descriptions.
`children`	React.ReactNode React.ReactNode	`—`	Content rendered inside this component.
`onFocus`	React.FocusEventHandler<HTMLDivElement> \| undefined React.FocusEventHandler<HTMLDivElement> \| undefined	`—`	Called when the control receives focus.
`onBlur`	React.FocusEventHandler<HTMLDivElement> \| undefined React.FocusEventHandler<HTMLDivElement> \| undefined	`—`	Called when the control loses focus.
`onChange`	React.ChangeEventHandler<HTMLDivElement, Element> \| undefined React.ChangeEventHandler<HTMLDivElement, Element> \| undefined	`—`	Called when the underlying form control changes; inspect the event for its value.
`onKeyDown`	React.KeyboardEventHandler<HTMLDivElement> \| undefined React.KeyboardEventHandler<HTMLDivElement> \| undefined	`—`	Called when a key is pressed while this element is focused.
`onClick`	React.MouseEventHandler<HTMLDivElement> \| undefined React.MouseEventHandler<HTMLDivElement> \| undefined	`—`	Called when the element is activated.

AvatarBadge

AvatarBadge properties
Prop	Type	Default	Description
`ref`	React.Ref<HTMLSpanElement> \| undefined React.Ref<HTMLSpanElement> \| undefined	`—`	Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref).
`defaultChecked`	boolean \| undefined boolean \| undefined	`—`	Initial checked state for an uncontrolled control.
`defaultValue`	string \| number \| readonly string[] \| undefined string \| number \| readonly string[] \| undefined	`—`	Initial value for an uncontrolled component.
`className`	string \| undefined string \| undefined	`—`	Additional CSS classes merged with the component styles.
`id`	string \| undefined string \| undefined	`—`	Unique identifier used to associate labels and descriptions.
`children`	React.ReactNode React.ReactNode	`—`	Content rendered inside this component.
`onFocus`	React.FocusEventHandler<HTMLSpanElement> \| undefined React.FocusEventHandler<HTMLSpanElement> \| undefined	`—`	Called when the control receives focus.
`onBlur`	React.FocusEventHandler<HTMLSpanElement> \| undefined React.FocusEventHandler<HTMLSpanElement> \| undefined	`—`	Called when the control loses focus.
`onChange`	React.ChangeEventHandler<HTMLSpanElement, Element> \| undefined React.ChangeEventHandler<HTMLSpanElement, Element> \| undefined	`—`	Called when the underlying form control changes; inspect the event for its value.
`onKeyDown`	React.KeyboardEventHandler<HTMLSpanElement> \| undefined React.KeyboardEventHandler<HTMLSpanElement> \| undefined	`—`	Called when a key is pressed while this element is focused.
`onClick`	React.MouseEventHandler<HTMLSpanElement> \| undefined React.MouseEventHandler<HTMLSpanElement> \| undefined	`—`	Called when the element is activated.

Usage notes

Provide meaningful alternative text for images. AvatarFallback remains useful while an image loads or fails.