Avatar

Stable

A compact visual identity for a person or an organization, with an image, initials fallback and optional presence status.

Source Base UI Registry

examples/avatar/demo.tsx

MCJOLPRS

Anatomy

GHKJMH

1RootA circle for people, a rounded square for organizations. Five sizes, from 20 to 56px.
2BadgeAn optional status dot, ringed in the page color so it separates from the image.
3FallbackInitials on a neutral fill, shown while the image loads — or instead of it, when there is none.
4GroupOverlapping avatars, each ringed in the page color.
5CountHow many more people there are, sized to match the group.

Installation

$ pnpm dlx shadcn@latest add https://www.prfct.dev/r/avatar.json

Usage

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

<Avatar>
  <AvatarImage src="/avatars/maya.png" alt="Maya Chen" />
  <AvatarFallback>MC</AvatarFallback>
</Avatar>

Always include an AvatarFallback. It renders while the image loads and permanently when the image is missing or fails, so a slow network or a deleted file never leaves a hole in the layout.

Examples

Sizes

Five sizes follow the control scale: xs 20, sm 24, default 32, lg 40 and xl 56 pixels. Initials scale with the avatar so they stay optically centered.

examples/avatar/sizes.tsx

MCMCMCMCMC

Size	Use it for
`xs`, `sm`	Inline mentions, dense tables, stacked assignees.
`default`	Lists, comments, menus, table rows.
`lg`	Cards, account switchers, member lists with two lines of text.
`xl`	Profile headers and settings pages — one per view.

Fallback

When there is no image, show two uppercase initials — given name and family name. For people you know nothing about, use a neutral icon and give it an accessible name.

examples/avatar/fallback.tsx

PRImage

PRInitials

Anonymous

Delaying the fallback

On fast connections the initials can flash for a frame before the image appears. Pass delay={600} to AvatarFallback to show it only when loading is genuinely slow.

Shape

Circles are for people; rounded squares are for things people belong to — workspaces, organizations, apps. The shape carries meaning, so keep it consistent across the product.

examples/avatar/shape.tsx

Maya ChenPerson · circle

NorthwindWorkspace · square

AvatarBadge sits on the bottom-right edge with a ring in the page color, so it reads on any background. It defaults to the success color for online; recolor it with a semantic token for other states, and always include a text label for screen readers.

examples/avatar/badge.tsx

MCJOLPRS

Group

Stack avatars to show who is involved without listing everyone. Show three to five, then summarize the rest with AvatarGroupCount. Each avatar gets a ring in the page color so overlaps stay crisp.

examples/avatar/group.tsx

MCJOLPPR

+12

MCJOLPPR

+12

MCJOLPPR

+12

With text

Most of the time an avatar sits next to a name. Because the name is already visible, the avatar is decorative: give the image an empty alt so assistive technology doesn't announce the name twice.

examples/avatar/with-text.tsx

Maya Chenmaya@northwind.dev

Owner

Guidelines

When to use

To help people recognize who did something: comment authors, assignees, collaborators, account owners.
To identify a workspace, organization or connected app in switchers and lists.

When not to use

For decorative or editorial imagery — use a regular image.
For objects that aren't people or organizations, such as files or integrations in a list — use Item with an icon.
As the only way to identify someone in a dense table. Pair it with a name, or make the name available in a tooltip.

Consistent identity

MCJONW

Do.Circles for people, squares for workspaces — the shape tells you what you're looking at.

MCJOLP

Don’t.Mixing shapes for the same kind of entity makes people look like organizations.

Initials

Do.Two uppercase letters: first letter of the given and the family name.

aik

Don’t.Three or more characters, lowercase, or emoji — they overflow at small sizes and read as noise.

Images

Use a square source at least twice the rendered size (112px for xl) so avatars stay sharp on high-density screens.
Crop around the face or logo; the avatar applies object-cover and clips to its shape.
Don't add borders — every avatar already has a hairline inner ring that keeps light images from dissolving into light surfaces.

Accessibility

Name the image. AvatarImage renders an <img>: set alt to the person's or organization's name. When the name is visible next to the avatar, set alt="" and add aria-hidden to the Avatar so the initials aren't announced as letters.
Status needs words. The badge is color and position only. Put a visually hidden label inside it (<span className="sr-only">Online</span>), and show presence as text wherever it matters.
Groups need a summary. Give AvatarGroup an aria-label that lists the people or states how many there are — "Project members: Maya Chen, Jonah Okafor and 12 others".
Contrast. Fallback initials (gray-11 on gray-4) meet 4.5:1 in both modes.

API reference

Avatar

The root. Accepts every prop of the Base UI Avatar Root.

Prop	Type	Default
`size` 20, 24, 32, 40 or 56 pixels. Fallback text and badge scale with it.	`"xs" \| "sm" \| "default" \| "lg" \| "xl"`	`"default"`
`shape` Circle for people, rounded square for organizations and apps.	`"circle" \| "square"`	`"circle"`
`render` Replaces the rendered span element.	`ReactElement \| (props, state) => ReactElement`	No default

AvatarImage

Prop	Type	Default
`src` Image URL. Loaded before it is shown; the fallback renders until then.	`string`	No default
`alt` Always set it: the person's or organization's name, or an empty string when the name is visible nearby.	`string`	No default
`onLoadingStatusChange` Called whenever the image's loading status changes.	`(status: "idle" \| "loading" \| "loaded" \| "error") => void`	No default
`keepMounted` Keeps the img element mounted and loads it in place — needed for lazy loading and optimized image components.	`boolean`	`false`

AvatarFallback

Prop	Type	Default
`delay` Milliseconds to wait before showing the fallback, to avoid a flash on fast connections.	`number`	`0`
`children` Two-letter initials or an icon.	`ReactNode`	No default