Avatar

CNQW

Installation

pnpm dlx shadcn@latest add @paneui/avatar

Usage

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

<Avatar>
  <AvatarImage src="https://github.com/QinYangWang.png" alt="Qinyang" />
  <AvatarFallback>CN</AvatarFallback>
</Avatar>

Composition

AvatarGroup
├── Avatar
│   ├── AvatarImage
│   ├── AvatarFallback
│   └── AvatarStatus
└── AvatarGroupCount

Examples

Basic

Sizes and Shapes

Fallback

Status

Group

Accessibility

Always give AvatarImage an alt. When the person's name is printed next to the avatar, an empty alt is fine. A status dot is decorative unless you pass label.

API Reference

Built on the Avatar primitive. Only the props this library adds or changes are listed; everything else passes through.

Also accepts every prop of Avatar.Root.

size= "md": "xs" | "sm" | "md" | "default" | "lg" | "xl"; Box size and fallback text size, from 20px at xs through 24, 32 and 40px to 48px at xl; default is the same as md. Inside an AvatarGroup it defaults to the group's size.
shape= "circle": "circle" | "rounded"; Round, or a squircle whose radius scales with the size (6–14px).

Prop	Type	Default	Description
size	"xs" \| "sm" \| "md" \| "default" \| "lg" \| "xl"	"md"	Box size and fallback text size, from 20px at `xs` through 24, 32 and 40px to 48px at `xl`; `default` is the same as `md`. Inside an `AvatarGroup` it defaults to the group's size.
shape	"circle" \| "rounded"	"circle"	Round, or a squircle whose radius scales with the size (6–14px).

data-size: The resolved size.
data-shape: The resolved shape.

Data attribute	Description
data-size	The resolved size.
data-shape	The resolved shape.

AvatarImage

Also accepts every prop of Avatar.Image.

AvatarFallback

Initials or an icon. Shows while the image loads and stays if it fails. Also accepts every prop of Avatar.Fallback.

delay: number; Milliseconds to wait before showing the fallback.

Prop	Type	Default	Description
delay	number	—	Milliseconds to wait before showing the fallback.

AvatarStatus

Presence dot at the bottom-right, sized from the avatar. Also accepts every prop of span.

status= "online": "online" | "away" | "busy" | "offline"; Presence state; sets the dot to the success, warning, destructive or muted token, in that order.
label: string; Accessible name (e.g. "Online"). Without it the dot is hidden from screen readers.

Prop	Type	Default	Description
status	"online" \| "away" \| "busy" \| "offline"	"online"	Presence state; sets the dot to the success, warning, destructive or muted token, in that order.
label	string	—	Accessible name (e.g. "Online"). Without it the dot is hidden from screen readers.

AvatarGroup

Overlapping stack with a background ring around each avatar. Also accepts every prop of div.

size= "md": "xs" | "sm" | "md" | "default" | "lg" | "xl"; Default size for every avatar inside, and the overlap.
shape= "circle": "circle" | "rounded"; Default shape for every avatar inside.

Prop	Type	Default	Description
size	"xs" \| "sm" \| "md" \| "default" \| "lg" \| "xl"	"md"	Default size for every avatar inside, and the overlap.
shape	"circle" \| "rounded"	"circle"	Default shape for every avatar inside.

AvatarGroupCount

The "+N" tile at the end of a group. Also accepts every prop of Avatar.