Skip to content

shadcn.io is an independent project built on shadcn/ui

Components

Free

Avatar for Radix UI

A round profile photo that shows initials when the picture is missing or broken, with a status dot and overlapping groups. For React on Radix UI.

On this page9 sections

An avatar shows who a comment, a table row or an account belongs to: a small round photo, with the person's initials in its place when the picture is missing or fails to load. A badge adds a status dot, and a group overlaps several faces with a count for the rest.

Use it wherever the screen names a person. To preview a profile on hover, put the avatar in a Hover Card trigger. A product photo or any picture that isn't a person belongs in a plain image.

Preview width

Installation

Sign in to get your install command
Free with an account. It carries your token, so the CLI installs everything in one go.

Anatomy

Avatar anatomy: image, badge, fallback, group, group count

Usage

import {
  Avatar, AvatarFallback, AvatarImage,
} from "@/components/ui/avatar";
<Avatar>
  <AvatarImage alt="shadcn" src="https://github.com/shadcn.png" />
  <AvatarFallback>CN</AvatarFallback>
</Avatar>

Accessibility

An avatar is a picture, not a control, so it takes no focus and has no keys. Radix UI leaves AvatarImage out of the page until the photo has loaded and renders AvatarFallback in its place, so a screen reader meets one or the other.

Two things are yours. Give AvatarImage an alt with the person's name, or an empty one when the name is printed beside it. A status dot is only a color, so put the status in words inside AvatarBadge, in a span with the sr-only class.

Demos

Basic

One avatar: the shadcn photo in grayscale, with CN as its fallback. The initials stay out of sight once the photo has loaded and take its place when the picture is missing or broken. Start here for a comment, a table row or a mention, and add a badge or a group from the demos below when the screen calls for one.

Preview width

Fallback

An Avatar with only AvatarFallback inside, holding the initials CN, for an account that has no photo at all. The muted circle keeps a list of people lined up with the rows that do have a picture. The same initials fill an Avatar whose photo is still loading or fails, so one fallback covers all three cases.

Preview width

Badge

A green dot on the bottom corner, an AvatarBadge with a background color and nothing inside it, marks this person as online. Use it for presence in a chat list or a team roster. The dot is only a color, so add the status in words for screen readers, as the Accessibility section explains.

Preview width

Badge icon

The same corner badge with a plus icon in it, on a grayscale photo, the mark that invites someone to add or change a picture. The icon is aria-hidden and the badge is a plain span, so the plus is only a picture until you put the avatar in a labeled button. At the sm size the badge hides its icon and shows a dot.

Preview width

Group

Three overlapping faces in an AvatarGroup, each ringed in the page background so the edges stay apart. Everyone in the set is on screen, so there is no count. Reach for it when the whole set fits, such as the reviewers on a pull request, and add AvatarGroupCount once some people are left out.

Preview width

Group count

The same three faces followed by a +3 circle from AvatarGroupCount. The component counts nothing: +3 is the text you put in it, so work it out from your list, the members minus the faces shown. Use it on a member list or the header of a shared document, where every face would push the row onto a second line.

Preview width

Group count icon

The trailing circle holds a plus icon instead of a number, which reads as an invitation to add someone rather than a hidden headcount. The icon is aria-hidden and the circle is not a button, so as it stands it is a picture. Put a button inside it with a label such as Invite people before you wire it to an invite dialog.

Preview width

Size

The three sizes side by side: sm at 24 pixels, the default at 32 and lg at 40, with each image's width and height set to match. The fallback's text drops a step at sm, and a badge or a group count follows the same size. Pick sm for dense tables and mentions, the default for comments and lists, and lg for a profile header.

Preview width

Square

The shadcn photo in a rounded square, with CN as its fallback: rounded-lg on Avatar, AvatarImage and AvatarFallback, plus after:rounded-lg for the outline the root draws. Pick it for a company, a workspace or a bot in a list that also shows people.

Preview width

The avatar sits in a round ghost Button that opens a menu with Profile, Billing, Settings and a destructive Log out, the account control at the end of an app header. The button is the trigger, which gives the menu a real control to focus and announce, and its aria-label, Account menu, says what pressing it does.

Preview width

RTL

The default row with dir set to rtl on the element around it. The row starts from the right, the status dot moves to the bottom-left corner, the group overlaps the other way, and the count reads +Ù£ with an Arabic-Indic digit. The photos aren't flipped. Use this when the page reads right to left.

Preview width

FAQ

How do I show initials when the Avatar image fails to load?

Put an AvatarFallback after AvatarImage in the same Avatar, with the person's initials or an icon in it. It takes the photo's place when src is empty or the request fails.

It also shows while the photo is still loading and steps aside once it arrives, so the circle never shows a broken image.

Work the initials out from the name in your data rather than typing them per avatar. The Basic demo shows the pair, and Fallback the initials alone.

How do I stop the Avatar fallback from flashing before the image loads?

Pass delayMs to AvatarFallback, such as 600. The initials then wait that long before they render, and a photo that loads in time never shows them. Without it they are in the server's HTML and the first paint, because Radix UI starts loading the photo in the browser after hydration and renders AvatarImage only once it has loaded.

How do I add an online status dot to an Avatar?

Put an AvatarBadge inside Avatar, after the image and the fallback, and give it a color class such as bg-green-600. It sits on the bottom corner at the end of the line, ringed in the page background, and grows from 8 to 12 pixels with the avatar's size. The Badge demo shows the dot.

A colored dot says nothing to a screen reader or to someone who can't tell green from gray. Put the status in words inside the badge, in a span with the sr-only class, or add it to the image's alt, such as Ada Lovelace, online.

How do I show a group of Avatars with a +N count?

Wrap the avatars in AvatarGroup, which overlaps them by 8 pixels and rings each one in the page background, then end it with an AvatarGroupCount for the rest, such as +5. The count is only the text you give it, so slice your list to the faces you show and put the length of the remainder in the circle, as the Group count demo does with +3.

The count circle takes the size of the avatars around it, 40 pixels in a group of lg ones. When people need the hidden names, put a link to the full member list inside it.

How do I change the size of an Avatar?

Set size on Avatar to sm, default or lg, which are 24, 32 and 40 pixels. The fallback's text, a badge and an AvatarGroupCount in the same group follow it, and the Size demo puts the three side by side.

For any other size, add a size class such as size-16 to Avatar and a larger text class to AvatarFallback, since the parts still style themselves for the default. Ask for a photo at least as large as the circle, twice that for high-density screens, so it stays sharp.

How do I make a square Avatar instead of a round one?

Change the radius on all three parts: add rounded-lg after:rounded-lg to Avatar, whose outline is drawn by an ::after layer, and rounded-lg to AvatarImage and AvatarFallback, as the Square demo does. Each part rounds itself, so missing one leaves a round photo inside a square outline, or square initials in a round one.

A square avatar is a common way to mark a company, a team or a bot, which keeps the round one meaning a person on a screen that lists both.

How do I open an account menu from an Avatar in React?

Put the Avatar in a round ghost Button and wrap that button in DropdownMenuTrigger with asChild, as the Dropdown demo does.

The button gives the menu a control to focus and announce, and the avatar is only its picture. Give the button an aria-label such as Account menu, as the demo does. Without one, it is named by the avatar inside it, which says whose account it is but not what pressing it does.

What alt text should an Avatar image have?

Use the person's name, such as Ada Lovelace, when the avatar is the only place it appears, as in a group or a menu button. When the name is printed right beside it, as in a comment header, give the image an empty alt so a screen reader doesn't say the name twice.

Leaving alt off is not the same as an empty one: the image then has no name, and screen readers announce it as an unlabeled image or by its file name.

API Reference

Avatar

<div> data-slot="avatar"

PropType
size?"default" | "sm" | "lg"

The size.

Type
"default" | "sm" | "lg"
Default
"default"
asChild?boolean

Merge props onto the child element instead of rendering a host.

className?string

Merged with the part's classes.

AttributeType
data-size?string

Mirrors size.

AvatarImage

<img> data-slot="avatar-image"

PropType
onLoadingStatusChange?{ bivarianceHack(status: ImageLoadingStatus): void; }["bivarianceHack"]

Called when the image's loading status changes: idle, loading, loaded or error.

Type
{ bivarianceHack(status: ImageLoadingStatus): void; }["bivarianceHack"]
asChild?boolean

Merge props onto the child element instead of rendering a host.

className?string

Merged with the part's classes.

AttributeType
data-state"visible" | "hidden"

"visible" or "hidden".

Type
"visible" | "hidden"

AvatarFallback

<span> data-slot="avatar-fallback"

PropType
delayMs?number

How long it waits before showing, in milliseconds, so a fast-loading image doesn't flash it.

asChild?boolean

Merge props onto the child element instead of rendering a host.

className?string

Merged with the part's classes.

AttributeType
data-state"hidden" | "visible"

"hidden" or "visible".

Type
"hidden" | "visible"

AvatarBadge

<span> data-slot="avatar-badge"

PropType
className?string

Merged with the part's classes.

AvatarGroup

<div> data-slot="avatar-group"

PropType
className?string

Merged with the part's classes.

AvatarGroupCount

<div> data-slot="avatar-group-count"

PropType
className?string

Merged with the part's classes.