Avatar for Ark UI

Profile photo in a circle, with initials when the image is missing.

Use it wherever a screen names a person. If the photo should open a profile, put it on a Hover Card trigger. In React, Ark UI swaps in those initials while the image loads or if it is missing.

Installation

Anatomy

Avatar
├── AvatarImage
└── AvatarFallback

Usage

import {
  Avatar, AvatarBadge, AvatarFallback, AvatarGroup, AvatarGroupCount,
  AvatarImage,
} from "@/components/ui/avatar";

<div className="flex flex-row flex-wrap items-center gap-6 md:gap-12">
  <Avatar>
    <AvatarImage
      alt="@shadcn"
      className="grayscale"
      height={32}
      src="https://github.com/shadcn.png"
      width={32}
    />
    <AvatarFallback>CN</AvatarFallback>
  </Avatar>
  <Avatar>
    <AvatarImage
      alt="@evilrabbit"
      height={32}
      src="https://github.com/evilrabbit.png"
      width={32}
    />
    <AvatarFallback>ER</AvatarFallback>
    <AvatarBadge className="bg-green-600 dark:bg-green-800" />
  </Avatar>
  <AvatarGroup className="grayscale">
    <Avatar>
      <AvatarImage
        alt="@shadcn"
        height={32}
        src="https://github.com/shadcn.png"
        width={32}
      />
      <AvatarFallback>CN</AvatarFallback>
    </Avatar>
    <Avatar>
      <AvatarImage
        alt="@maxleiter"
        height={32}
        src="https://github.com/maxleiter.png"
        width={32}
      />
      <AvatarFallback>LR</AvatarFallback>
    </Avatar>
    <Avatar>
      <AvatarImage
        alt="@evilrabbit"
        height={32}
        src="https://github.com/evilrabbit.png"
        width={32}
      />
      <AvatarFallback>ER</AvatarFallback>
    </Avatar>
    <AvatarGroupCount>+3</AvatarGroupCount>
  </AvatarGroup>
</div>

Demos

Basic

One photo and the initials behind it. AvatarFallback is what remains when src is missing or the request fails, so the circle is never an empty hole, and the grayscale here is only the picture treatment. Start with this pair. Every other avatar on the page is the same two parts with a badge, a group, or a menu added.

Badge

A green dot on the corner, from AvatarBadge with a background class and no icon, which reads as presence. The color is yours to pick, and on the small size the badge stays a plain dot. Use it for online, away, or busy. A count of people who did not fit belongs on the group, not in this corner.

Badge Icon

The same corner badge, with a plus icon inside instead of a bare dot. Use it when the mark means an action, such as adding a photo, rather than a status color. The icon is hidden from assistive tech, so a clickable plus needs a button and a name of its own. A green dot with no icon is the presence version.

Group

Three faces overlapped in AvatarGroup, and nobody is left out, so there is no count. Use it when the whole set fits, such as the people on a small pull request, and a row of full circles would waste the line. Add AvatarGroupCount once someone is hidden. The grayscale is optional, and the overlap is the point.

Group Count

The same pile, plus a +3 in AvatarGroupCount for the people who did not fit. You pass that text, and it is not counted from the children. Use it on a member list or a share row where showing every face would wrap. If the last slot should invite someone instead of reporting a number, put an icon there.

Group Count Icon

The last slot holds a plus icon rather than a number, at the end of the pile, which reads as invite or add rather than a hidden headcount. Use it when the trailing item is an action. The icon in this file is decorative, so wrap the slot in a button with a label before it actually invites anyone, or the plus is only a picture.

Size

sm, the default, and lg, with the bitmap matched to the circle: 24, 32, and 40 pixels here. Use small in a dense table, the default beside a comment, and large on a profile header. A mismatch between size and the image dimensions is how the photo goes soft. The fallback initials follow the same prop.

Dropdown

The avatar sits inside a round ghost button, and that button opens the menu: profile, billing, settings, and log out. Use this for the account control in a header. Keep the Dropdown Menu trigger on the button so the hit target and the accessible name stay on a real control. The avatar is the face inside it, not the trigger itself.

Rtl

dir is rtl on the row, so the status dot and the overlap move to the other side, and the overflow count uses an Arabic-Indic numeral. Use this when the surrounding page is right to left. The photos themselves are not mirrored. Only the pile, the badge corner, and the count follow the direction.

FAQ

API Reference