Avatar
An image element with a text fallback for representing a user or entity.
Installation
$
npx shadcn@latest add https://ui.mattdowney.com/r/avatar.jsonUsage
import { Avatar, AvatarImage, AvatarFallback } from "@/components/ui/avatar"
import { AvatarGroup } from "@/components/ui/avatar-group"Examples
Default
Image with a text fallback, plus an optional status dot.
MDUI
SCOnline
Sizes
Five sizes from one prop. The fallback text scales with the box.
MDMDMDMDMD
Group
A row of overlapping people, such as a team or the people on a document. Each avatar is ringed in the colour of the surface behind it, so the row works on the page and on a card. max folds the rest into a +N chip. Point at one to lift it; the row springs back when the pointer leaves.
MDSCPNSO+33 more
Group of links
When each person opens their profile, wrap each Avatar in a bare Button with a round focus ring. Keyboard focus lifts the avatar the same way the pointer does.
API Reference
| Prop | Type | Default | Description |
|---|---|---|---|
| sizeAvatar | "xs" | "sm" | "default" | "lg" | "xl" | "default" | The avatar size: xs (20px, beside 14px text), sm (24px), default (32px), lg (40px), or xl (48px). The fallback text scales with it, so you never set two classes. |
| srcAvatarImage | string | None | Image source URL. The image only renders once it has loaded; the fallback shows until then. |
| onLoadingStatusChangeAvatarImage | (status: "idle" | "loading" | "loaded" | "error") => void | None | Called when the image's loading status changes. |
| delayMsAvatarFallback | number | None | Delay in milliseconds before the fallback renders, avoiding a flash when the image loads quickly. |
| sizeAvatarGroup | "xs" | "sm" | "default" | "lg" | "xl" | "default" | Every avatar in the row takes this size, and the overlap (about a fifth of the avatar: 4, 4, 6, 8 and 10px), ring and lift scale with it. An Avatar's own size still wins. |
| maxAvatarGroup | number | None | Show at most this many avatars. The rest fold into a +N chip at the end, read aloud as "N more". |
| aria-labelAvatarGroup | string | None | Names the group for screen readers: who these people are ("Team", "People on this call"). |
sizeAvatar"xs" | "sm" | "default" | "lg" | "xl" = "default"The avatar size: xs (20px, beside 14px text), sm (24px), default (32px), lg (40px), or xl (48px). The fallback text scales with it, so you never set two classes. |
| srcAvatarImagestringImage source URL. The image only renders once it has loaded; the fallback shows until then. |
| onLoadingStatusChangeAvatarImage(status: "idle" | "loading" | "loaded" | "error") => voidCalled when the image's loading status changes. |
| delayMsAvatarFallbacknumberDelay in milliseconds before the fallback renders, avoiding a flash when the image loads quickly. |
sizeAvatarGroup"xs" | "sm" | "default" | "lg" | "xl" = "default"Every avatar in the row takes this size, and the overlap (about a fifth of the avatar: 4, 4, 6, 8 and 10px), ring and lift scale with it. An Avatar's own size still wins. |
| maxAvatarGroupnumberShow at most this many avatars. The rest fold into a +N chip at the end, read aloud as "N more". |
| aria-labelAvatarGroupstringNames the group for screen readers: who these people are ("Team", "People on this call"). |
"use client"
import * as React from "react"
import { Avatar as AvatarPrimitive } from "@base-ui/react/avatar"
import { cn } from "@/registry/lib/utils"
type AvatarSize = "xs" | "sm" | "default" | "lg" | "xl"
// Set by AvatarGroup (avatar-group.tsx) so every avatar in the row takes the
// group's size and its separating ring without the caller repeating either.
const AvatarGroupContext = React.createContext<{ size: AvatarSize } | null>(null)
// The ring that cuts each avatar out of the one it overlaps. Its colour is
// the surface behind the row, which AvatarGroup sets as
// `--avatar-group-ring`; its width steps with the avatar, about 6% of the box.
const GROUP_RING =
"ring-(color:--avatar-group-ring) data-[size=xs]:ring-1 data-[size=sm]:ring-2 data-[size=default]:ring-2 data-[size=lg]:ring-2 data-[size=xl]:ring-3"
// @use-when a person or account's image (a profile picture, or their initials
// when there is none), often beside their name and email. Not Button, which is
// the press itself: a clickable avatar is Button `variant="bare"` around this.
function Avatar({
size: sizeProp,
className,
...props
}: React.ComponentProps<typeof AvatarPrimitive.Root> & {
/** 20 / 24 / 32 / 40 / 48px. The fallback's type scales with it. `xs`
* is media beside 14px text: sized to the label's line box, never taller. */
size?: AvatarSize
}) {
const group = React.useContext(AvatarGroupContext)
const size = sizeProp ?? group?.size ?? "default"
return (
<AvatarPrimitive.Root
data-slot="avatar"
data-size={size}
className={cn(
"group/avatar relative flex shrink-0 overflow-hidden rounded-full",
// The box and the fallback's type are ONE decision, so the size lives
// here and the fallback reads it off `data-size` rather than asking the
// caller to send a matching `text-*`. Hand-syncing those two classes is
// the same faked-size pattern `verify-ui` flags on Button.
"data-[size=xs]:size-5",
"data-[size=sm]:size-6",
"data-[size=default]:size-8",
"data-[size=lg]:size-10",
"data-[size=xl]:size-12",
group && GROUP_RING,
className
)}
{...props}
/>
)
}
function AvatarImage({
className,
...props
}: React.ComponentProps<typeof AvatarPrimitive.Image>) {
return (
<AvatarPrimitive.Image
data-slot="avatar-image"
className={cn("aspect-square size-full", className)}
{...props}
/>
)
}
function AvatarFallback({
className,
...props
}: React.ComponentProps<typeof AvatarPrimitive.Fallback>) {
return (
<AvatarPrimitive.Fallback
data-slot="avatar-fallback"
className={cn(
"bg-neutral-200 text-muted-foreground dark:bg-neutral-800 flex size-full items-center justify-center rounded-full font-medium",
// Type steps with the root's size, one decision, never two classes.
// 11px is the floor of the type scale, so `xs` shares it with `sm`.
"group-data-[size=xs]/avatar:text-2xs",
"group-data-[size=sm]/avatar:text-2xs",
"group-data-[size=default]/avatar:text-xs",
"group-data-[size=lg]/avatar:text-sm",
"group-data-[size=xl]/avatar:text-base",
className
)}
{...props}
/>
)
}
export { Avatar, AvatarImage, AvatarFallback, AvatarGroupContext, type AvatarSize }"use client"
import * as React from "react"
import { cn } from "@/registry/lib/utils"
import {
Avatar,
AvatarFallback,
AvatarGroupContext,
type AvatarSize,
} from "@/registry/ui/avatar"
// The row's shape, one decision per size. Each avatar overlaps the one before
// it by about a fifth of its width, on the spacing scale (4, 4, 6, 8, 10px).
// A quarter cut the second letter off two-letter initials. The lift is an
// eighth of the box (xs rounds down to 2px).
const SIZE = [
"data-[size=xs]:*:not-first:-ms-1 data-[size=xs]:[--avatar-group-lift:--spacing(0.5)]",
"data-[size=sm]:*:not-first:-ms-1 data-[size=sm]:[--avatar-group-lift:--spacing(0.75)]",
"data-[size=default]:*:not-first:-ms-1.5 data-[size=default]:[--avatar-group-lift:--spacing(1)]",
"data-[size=lg]:*:not-first:-ms-2 data-[size=lg]:[--avatar-group-lift:--spacing(1.25)]",
"data-[size=xl]:*:not-first:-ms-2.5 data-[size=xl]:[--avatar-group-lift:--spacing(1.5)]",
]
// The ring around each avatar is the colour of the surface behind the row, so
// it reads as a cut, not an outline. The page by default; a card or a popup
// when the row sits on one. On any other fill, set `--avatar-group-ring`.
const RING =
"[--avatar-group-ring:var(--background)] in-data-[slot=card]:[--avatar-group-ring:var(--card)] in-data-[slot=popover-content]:[--avatar-group-ring:var(--popover)] in-data-[slot=dialog-content]:[--avatar-group-ring:var(--popover)]"
// The lift. Every item moves by `--avatar-group-lift` times its own
// `--avatar-group-k`: 1 for the avatar under the pointer (which also grows 5%
// and comes to the front), the falloff (0.45) one place away, the falloff
// squared (about 0.2) two places away, and 0 beyond. Translate and scale only,
// so the row never changes size and nothing beside it moves.
// Keyboard focus on an item that is a Button or link lifts it the same way.
// Under reduced motion none of the k rules apply, so nothing lifts.
const LIFT = [
"[--avatar-group-k:0] [--avatar-group-falloff:0.45]",
"*:translate-y-[calc(var(--avatar-group-lift)*var(--avatar-group-k)*-1)]",
"motion-safe:[@media(hover:hover)]:[&>:hover]:[--avatar-group-k:1] motion-safe:[@media(hover:hover)]:[&>:hover]:scale-105 [@media(hover:hover)]:[&>:hover]:z-10",
"motion-safe:[@media(hover:hover)]:[&>:has(+:hover)]:[--avatar-group-k:var(--avatar-group-falloff)] motion-safe:[@media(hover:hover)]:[&>:hover+*]:[--avatar-group-k:var(--avatar-group-falloff)]",
"motion-safe:[@media(hover:hover)]:[&>:has(+*+:hover)]:[--avatar-group-k:calc(var(--avatar-group-falloff)*var(--avatar-group-falloff))] motion-safe:[@media(hover:hover)]:[&>:hover+*+*]:[--avatar-group-k:calc(var(--avatar-group-falloff)*var(--avatar-group-falloff))]",
"motion-safe:[&>:focus-visible]:[--avatar-group-k:1] motion-safe:[&>:focus-visible]:scale-105 [&>:focus-visible]:z-10",
"motion-safe:[&>:has(+:focus-visible)]:[--avatar-group-k:var(--avatar-group-falloff)] motion-safe:[&>:focus-visible+*]:[--avatar-group-k:var(--avatar-group-falloff)]",
"motion-safe:[&>:has(+*+:focus-visible)]:[--avatar-group-k:calc(var(--avatar-group-falloff)*var(--avatar-group-falloff))] motion-safe:[&>:focus-visible+*+*]:[--avatar-group-k:calc(var(--avatar-group-falloff)*var(--avatar-group-falloff))]",
]
// Two clocks, one per direction, the named exception in the rules (Expressive
// motion, "Never give a kit component this role"). While the pointer or focus
// is in the row, every item moves on `ease-expressive` at the short expressive
// duration, a soft rise with no overshoot. When it leaves, they settle back on
// `ease-expressive-rebound` at the long one, so the row lands with a springy bounce.
// A row of small marks settling is the one exit allowed to bounce: nothing in
// it holds text to read.
// motion-role-exempt: the hover lift is the rules' named exception (Expressive motion), an expressive rise and a bouncing settle on a row of small marks
const TIMING =
"*:transition-[translate,scale] *:duration-expressive-in *:ease-expressive-rebound *:motion-reduce:transition-none hover:*:duration-expressive-out hover:*:ease-expressive has-[>:focus-visible]:*:duration-expressive-out has-[>:focus-visible]:*:ease-expressive"
// @use-when a row of people shown as overlapping avatars: who is on a team, a
// document or a call, the members using a plan's seats. `max` folds the rest
// into a "+N" chip. Not a list of members with names, roles or actions, which
// is a Table or CardRows with an Avatar in each row.
function AvatarGroup({
size = "default",
max,
className,
children,
...props
}: React.ComponentProps<"div"> & {
/** Every avatar in the row takes this size: `xs` (20px) to `xl` (48px),
* the same names as Avatar. The overlap, ring and lift scale with it. */
size?: AvatarSize
/** Show at most this many avatars; the rest fold into a "+N" chip at the
* end, read aloud as "N more". */
max?: number
}) {
const items = React.Children.toArray(children)
const hidden = max !== undefined && items.length > max ? items.length - max : 0
const shown = hidden ? items.slice(0, max) : items
return (
<AvatarGroupContext.Provider value={{ size }}>
<div
role="group"
data-slot="avatar-group"
data-size={size}
className={cn("flex isolate items-center", SIZE, RING, LIFT, TIMING, className)}
{...props}
>
{shown}
{hidden > 0 && (
<Avatar>
<AvatarFallback aria-hidden="true">+{hidden}</AvatarFallback>
<span className="sr-only">{hidden} more</span>
</Avatar>
)}
</div>
</AvatarGroupContext.Provider>
)
}
export { AvatarGroup }