- Accordion
- Alert
- Alert Dialog
- Autocomplete
- Avatar
- Badge
- Breadcrumb
- Button
- Calendar
- Card
- Checkbox
- Checkbox Group
- Collapsible
- Combobox
- ComposerNew
- Command
- Context Menu
- Date Picker
- Dialog
- Drawer
- Empty
- Field
- Fieldset
- Form
- Frame
- Group
- Input
- Input Group
- Kbd
- Label
- Menu
- Meter
- Number Field
- OTP Field
- Pagination
- Popover
- Preview Card
- Progress
- Radio Group
- Scroll Area
- Select
- Segmented Control
- Separator
- Sheet
- Skeleton
- Slider
- Spinner
- Switch
- Table
- Tabs
- Textarea
- Toast
- Toggle
- Toggle Group
- Toolbar
- Tooltip
Avatar
An image element with a fallback for representing the user.
import {
Avatar,
AvatarFallback,
AvatarImage,
} from "@/components/ui/avatar";
export default function Particle() {
return (
<Avatar>
<AvatarImage
alt="Luke Tracy"
src="https://images.unsplash.com/photo-1543610892-0b1f7e6d8ac1?w=128&h=128&dpr=2&q=80"
/>
<AvatarFallback>LT</AvatarFallback>
</Avatar>
);
}
Installation
pnpm dlx shadcn@latest add @coss/avatar
Usage
import {
Avatar,
AvatarFallback,
AvatarGroup,
AvatarGroupCount,
AvatarImage,
} from "@/components/ui/avatar"<Avatar>
<AvatarImage src="/avatars/01.png" alt="User avatar" />
<AvatarFallback>JD</AvatarFallback>
</Avatar>Use keepMounted when the image relies on native lazy loading or an optimized image component. The fallback remains visible while the image loads or if it fails:
<Avatar>
<AvatarImage
src="/avatars/01.png"
alt="User avatar"
loading="lazy"
keepMounted
/>
<AvatarFallback>JD</AvatarFallback>
</Avatar>Sizing
Every dimension of an avatar comes from one inherited custom property, --avatar-size. It defaults to 32px, and the font size, the group overlap, the gap and the initials nudge are all derived from it.
Set it on the avatar, on a group, or on any ancestor:
<Avatar className="[--avatar-size:--spacing(12)]">…</Avatar>
<AvatarGroup className="[--avatar-size:--spacing(6)]">…</AvatarGroup>
<div className="[--avatar-size:--spacing(10)]">
{/* every avatar below is 40px */}
</div>A size-* utility still resizes a single avatar, because tailwind-merge replaces the base size utility. It does not update --avatar-size, so the font size and any group geometry stay at the inherited value. Prefer --avatar-size and reach for size-* only when you want the box to change and nothing else.
import {
Avatar,
AvatarFallback,
AvatarImage,
} from "@/components/ui/avatar";
export default function Particle() {
return (
<div className="flex flex-col gap-4">
<div className="flex items-center gap-4">
<Avatar className="[--avatar-size:--spacing(4)]">
<AvatarImage
alt="User"
src="https://images.unsplash.com/photo-1543610892-0b1f7e6d8ac1?w=48&h=48&dpr=2&q=80"
/>
<AvatarFallback>AV</AvatarFallback>
</Avatar>
<Avatar className="[--avatar-size:--spacing(6)]">
<AvatarImage
alt="User"
src="https://images.unsplash.com/photo-1543610892-0b1f7e6d8ac1?w=72&h=72&dpr=2&q=80"
/>
<AvatarFallback>AV</AvatarFallback>
</Avatar>
<Avatar className="[--avatar-size:--spacing(8)]">
<AvatarImage
alt="User"
src="https://images.unsplash.com/photo-1543610892-0b1f7e6d8ac1?w=96&h=96&dpr=2&q=80"
/>
<AvatarFallback>AV</AvatarFallback>
</Avatar>
<Avatar className="[--avatar-size:--spacing(10)]">
<AvatarImage
alt="User"
src="https://images.unsplash.com/photo-1543610892-0b1f7e6d8ac1?w=120&h=120&dpr=2&q=80"
/>
<AvatarFallback>AV</AvatarFallback>
</Avatar>
<Avatar className="[--avatar-size:--spacing(12)]">
<AvatarImage
alt="User"
src="https://images.unsplash.com/photo-1543610892-0b1f7e6d8ac1?w=144&h=144&dpr=2&q=80"
/>
<AvatarFallback>AV</AvatarFallback>
</Avatar>
</div>
<div className="flex items-center gap-4">
<Avatar className="[--avatar-size:--spacing(4)]">
<AvatarFallback>AV</AvatarFallback>
</Avatar>
<Avatar className="[--avatar-size:--spacing(6)]">
<AvatarFallback>AV</AvatarFallback>
</Avatar>
<Avatar className="[--avatar-size:--spacing(8)]">
<AvatarFallback>AV</AvatarFallback>
</Avatar>
<Avatar className="[--avatar-size:--spacing(10)]">
<AvatarFallback>AV</AvatarFallback>
</Avatar>
<Avatar className="[--avatar-size:--spacing(12)]">
<AvatarFallback>AV</AvatarFallback>
</Avatar>
</div>
</div>
);
}
Because the property is inherited, one declaration on a container sizes every avatar inside it.
API Reference
Avatar
Root component. Styled wrapper for Avatar.Root from Base UI, round by default and sized from --avatar-size.
It declares no props of its own; everything from Avatar.Root passes through, including className and render.
It renders a <span>. To make an avatar interactive, use render rather than wrapping it:
<Avatar render={<button type="button" />}>…</Avatar>
<Avatar render={<a href="/people/ada" />}>…</Avatar>An interactive avatar needs an accessible name. AvatarImage's alt supplies one; a fallback-only avatar does not, so add aria-label.
AvatarImage
Image element. Styled wrapper for Avatar.Image from Base UI.
| Prop | Type | Default | Description |
|---|---|---|---|
keepMounted | boolean | false | Keep the image mounted and let it load in place, for loading="lazy" and next/image |
onLoadingStatusChange | (status: ImageLoadingStatus) => void | - | Fired when loading status changes: "idle", "loading", "loaded" or "error" |
AvatarFallback
Shown while the image loads or when it fails, and whenever no image is given. Base UI unmounts it once the image loads.
| Prop | Type | Default | Description |
|---|---|---|---|
delay | number | 0 | Milliseconds to wait before showing the fallback |
It inherits its font size from the avatar, so it scales automatically. Override it on the fallback when a specific size is needed:
<AvatarFallback className="text-[10px]">JD</AvatarFallback>AvatarGroup
Lays out overlapping avatars. Each avatar is masked with a circle matching its neighbour, so the avatars are separated by a transparent gap rather than a ring. The stack therefore holds its shape on gradients, images and translucent panels, where a ring tinted with the page background would not.
| Prop | Type | Default | Description |
|---|---|---|---|
topmost | "first" | "last" | "first" | Which end of the stack stays a whole circle. |
Geometry is derived from the inherited --avatar-size, so sizing a stack is the same gesture as sizing one avatar. Three further properties tune the layout, and all of them inherit:
| Property | Default | Description |
|---|---|---|
--avatar-overlap | calc(var(--avatar-size) * 0.3) | How far each avatar sits over the previous one. |
--avatar-gap | calc(var(--avatar-size) / 16) | Thickness of the transparent gap. |
--avatar-nudge | calc((var(--avatar-overlap) + var(--avatar-gap)) * 0.3) | How far initials shift out of the clipped edge. Set to 0 to centre them geometrically. |
<AvatarGroup className="[--avatar-size:--spacing(12)] [--avatar-overlap:--spacing(7)]">
…
</AvatarGroup>Constraints worth knowing:
- Every avatar in a group must be the same size. The mask is positioned from the group's
--avatar-size, so a per-avatar override misplaces the cut. Set the size on the group. - A status dot or badge on a clipped avatar is clipped with it, and is cropped to the circle. Put one on the avatar that stays whole — the first with
topmost="first", the last withtopmost="last". - Browsers without
mask-composite(Chrome and Edge 111–119) fall back to a plain overlap with no gap. Nothing else degrades.
AvatarGroupCount
The "+N" chip that ends a group. It is an Avatar with a fallback, so it is sized, overlapped and clipped like its neighbours; its label uses text-muted-foreground.
<AvatarGroup>
<Avatar>…</Avatar>
<AvatarGroupCount>+2</AvatarGroupCount>
</AvatarGroup>Examples
Fallback Only
import { Avatar, AvatarFallback } from "@/components/ui/avatar";
export default function Particle() {
return (
<Avatar>
<AvatarFallback>LT</AvatarFallback>
</Avatar>
);
}
Different Radius
import {
Avatar,
AvatarFallback,
AvatarImage,
} from "@/components/ui/avatar";
export default function Particle() {
return (
<div className="flex items-center gap-4">
<Avatar className="rounded-md">
<AvatarImage
alt="User"
src="https://images.unsplash.com/photo-1543610892-0b1f7e6d8ac1?w=128&h=128&dpr=2&q=80"
/>
<AvatarFallback>AV</AvatarFallback>
</Avatar>
<Avatar className="rounded-xl">
<AvatarImage
alt="User"
src="https://images.unsplash.com/photo-1543610892-0b1f7e6d8ac1?w=128&h=128&dpr=2&q=80"
/>
<AvatarFallback>AV</AvatarFallback>
</Avatar>
<Avatar className="rounded-full">
<AvatarImage
alt="User"
src="https://images.unsplash.com/photo-1543610892-0b1f7e6d8ac1?w=128&h=128&dpr=2&q=80"
/>
<AvatarFallback>AV</AvatarFallback>
</Avatar>
</div>
);
}
Group Avatars
import {
Avatar,
AvatarFallback,
AvatarGroup,
AvatarGroupCount,
AvatarImage,
} from "@/components/ui/avatar";
export default function Particle() {
return (
<AvatarGroup>
<Avatar>
<AvatarImage
alt="Frida Kahlo"
src="https://images.unsplash.com/photo-1543610892-0b1f7e6d8ac1?w=96&h=96&dpr=2&q=80"
/>
<AvatarFallback>FK</AvatarFallback>
</Avatar>
<Avatar>
<AvatarImage
alt="Nadia Ekman"
src="https://images.unsplash.com/photo-1628157588553-5eeea00af15c?w=96&h=96&dpr=2&q=80"
/>
<AvatarFallback>NE</AvatarFallback>
</Avatar>
<Avatar>
<AvatarImage
alt="Eli Wren"
src="https://images.unsplash.com/photo-1655874819398-c6dfbec68ac7?w=96&h=96&dpr=2&q=80"
/>
<AvatarFallback>EW</AvatarFallback>
</Avatar>
<AvatarGroupCount>+2</AvatarGroupCount>
</AvatarGroup>
);
}
Last Avatar On Top
Set topmost="last" for the conventional order, where the last avatar is the one left intact.
import {
Avatar,
AvatarFallback,
AvatarGroup,
AvatarGroupCount,
AvatarImage,
} from "@/components/ui/avatar";
export default function Particle() {
return (
<AvatarGroup topmost="last">
<Avatar>
<AvatarImage
alt="Frida Kahlo"
src="https://images.unsplash.com/photo-1543610892-0b1f7e6d8ac1?w=96&h=96&dpr=2&q=80"
/>
<AvatarFallback>FK</AvatarFallback>
</Avatar>
<Avatar>
<AvatarImage
alt="Nadia Ekman"
src="https://images.unsplash.com/photo-1628157588553-5eeea00af15c?w=96&h=96&dpr=2&q=80"
/>
<AvatarFallback>NE</AvatarFallback>
</Avatar>
<Avatar>
<AvatarImage
alt="Eli Wren"
src="https://images.unsplash.com/photo-1655874819398-c6dfbec68ac7?w=96&h=96&dpr=2&q=80"
/>
<AvatarFallback>EW</AvatarFallback>
</Avatar>
<AvatarGroupCount>+2</AvatarGroupCount>
</AvatarGroup>
);
}
Changelog
- October 18, 2026 —
AvatarGroupandAvatarGroupCountadded; overlapping avatars are separated by a transparent clipped gap instead of a ring.Avatarnow derives its box, type and group geometry from the inherited--avatar-size.AvatarFallbackmoves frombg-mutedtobg-border, andAvatarno longer paintsbg-background.