Avatar

An easily stylable avatar component.

Preview

Image, generated avatar, initials, and fallback.

MCIllustration

DYGenerated

MCInitials

MCFallback

Installation

Install the local ghost-kit source bundle while the registry runs at localhost:3110. It contains this component and its source dependencies. Prepare the local registry first so token dependencies also resolve locally.

Install

npx shadcn@latest add http://localhost:3110/r/ghost-kit.json

Basic usage

123import { Avatar } from "@/components/ui/avatar";

<Avatar name="Ada Lovelace" />

Structure

Examples

Image

Use Image for a person or other identity photo. Keep Fallback in the same Root for a missing or failed image.

Generated

Five DiceBear styles use the same seed. If the service is unavailable, each avatar shows its fallback.

GUgaze

GUdylan

GUline-face

GUsprouts

GUshadows

Initials

Use the identity API when a photo is not available. Initials are derived from name unless initials is provided.

Failed image fallback

Keep a useful identity when an image request fails. The fallback is part of the same avatar composition.

Labeled status

Wrap an avatar before adding a status indicator. Add a label when the status conveys information beyond decoration.

Stacked identities

Compose Avatar when a task needs a compact member list. The example keeps the group layout local and shows the remaining count when the list is capped.

MCSLRP+2

API reference

For inherited behavior and additional part properties, see the Base UI Avatar API.

Avatar.Root properties
Prop	Type	Description
`className`	`string \| ((state: AvatarRootState) => string)`	CSS class applied to the element, or a function that returns a class based on the component's state.
`style`	`React.CSSProperties \| ((state: AvatarRootState) => React.CSSProperties)`	Style applied to the element, or a function that returns a style object based on the component's state.
`render`	`React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, AvatarRootState>`	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.