Avatar in six sizes with an image to initials to icon fallback chain, presence, verified and logo corners, plus a stack that fans out on hover; photos blur up into focus.
avataruserprofilepresencestatusgroupinitials
Installation
$npx shadcn@latest add @geturui/avatar
Usage
usage.tsx
1import { Avatar, AvatarGroup, AvatarLabel } from "@/components/ui/avatar";
2
3export function Reviewers() {
4 return (
5 <div className="flex items-center gap-6">
6 <AvatarLabel name="Mei Tanaka" supporting="[email protected]" src="/team/mei.jpg" status="online" />
7 <AvatarGroup max={3} label="Reviewers" onAdd={() => {}}>
8 <Avatar name="Theo Laurent" src="/team/theo.jpg" />
9 <Avatar name="Priya Raman" verified />
10 <Avatar name="Jonah Okafor" />
11 <Avatar name="Sofia Marin" />
12 </AvatarGroup>
13 </div>
14 );
15}
Props
| Prop | Type | Default | Description |
|---|---|---|---|
size | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "md" | 24, 32, 40, 48, 56 or 64px. |
src | string | null | — | Image URL. On error the avatar falls back to initials, then the placeholder icon. |
name | string | — | Drives the initials, a deterministic tint (same name, same colour) and the accessible name. |
initials | string | — | Override the initials derived from name. |
icon | ReactNode | — | Placeholder when there is no image and no name. Defaults to a user glyph. |
shape | "circle" | "square" | "circle" | Square suits companies and workspaces. |
status | "online" | "away" | "busy" | "offline" | — | Presence dot, announced as a word. Online breathes softly. |
verified | boolean | false | Volt check badge. Moves to the top-right corner when status is set. |
badge | ReactNode | — | Small round node in the bottom-right corner, e.g. a company logo. |
bordered | boolean | false | Thin outer ring for busy backgrounds. |
decorative | boolean | false | Hide from screen readers when a visible name sits beside it. |
AvatarGroup | { size, max, label, onAdd, addLabel } | — | Overlapping stack; members past max collapse into a +N chip that names them. onAdd renders a dashed add button. |
AvatarLabel | { name, supporting, size: sm | md | lg } & AvatarProps | — | Avatar beside a name and an email or role line. |
--avatar-cut | CSS variable | var(--color-bg) | Colour of the cut-out rings around corners and stacked avatars. Set it to the surface the avatar sits on. |
Accessibility
- The avatar is role="img" with a name that includes presence and verification, e.g. "Mei Tanaka, online, verified" — never colour alone.
- AvatarLabel hides the avatar and puts the status words next to the visible name instead.
- The +N chip lists the hidden names; the add button has a label.
- Blur-up, breathing halo and fan-out are skipped under reduced motion.