Avatar

An image element with a fallback for representing the user.

<Avatar>
  <AvatarImage src="/docs/avatar/cn.png" alt="CN" />
  <AvatarFallback>CN</AvatarFallback>
</Avatar>

Installation

pnpm dlx cubix@latest add avatar --base aria

Usage

Import

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

Example

<Avatar>
  <AvatarImage src="/docs/avatar/cn.png" alt="CN" />
  <AvatarFallback>CN</AvatarFallback>
</Avatar>

Composition

Use the following composition to build an Avatar:

Avatar
├── AvatarImage
├── AvatarFallback
└── AvatarBadge

Use the following composition to build an Avatar Group:

AvatarGroup
├── Avatar
├── Avatar
└── AvatarGroupCount

Examples

Badge

Use AvatarBadge for a status dot. Override the color with className. Give the badge an aria-label so the status is announced.

<Avatar>
  <AvatarImage src="/docs/avatar/er.png" alt="ER" />
  <AvatarFallback>ER</AvatarFallback>
  <AvatarBadge aria-label="Online" className="bg-green-600 dark:bg-green-800" />
</Avatar>

Badge with icon

For real actions, compose AvatarBadge onto a button with render (Base UI / React Aria) or asChild (Radix), and give it an aria-label.

<Avatar>
  <AvatarImage src="/docs/avatar/cn.png" alt="CN" />
  <AvatarFallback>CN</AvatarFallback>
  <AvatarBadge
    aria-label="Add teammate"
    render={<button type="button" />}
  >
    <PlusIcon />
  </AvatarBadge>
</Avatar>

Avatar Group

Stack avatars with AvatarGroup. Label the group so the set of people is announced.

CNLRER

<AvatarGroup aria-label="Team">
  <Avatar>
    <AvatarImage src="/docs/avatar/cn.png" alt="CN" />
    <AvatarFallback>CN</AvatarFallback>
  </Avatar>
  <Avatar>
    <AvatarImage src="/docs/avatar/lr.png" alt="LR" />
    <AvatarFallback>LR</AvatarFallback>
  </Avatar>
  <Avatar>
    <AvatarImage src="/docs/avatar/er.png" alt="ER" />
    <AvatarFallback>ER</AvatarFallback>
  </Avatar>
</AvatarGroup>

Group count

Use AvatarGroupCount to show remaining people.

CNLRER

<AvatarGroup aria-label="Team">
  <Avatar>
    <AvatarImage src="/docs/avatar/cn.png" alt="CN" />
    <AvatarFallback>CN</AvatarFallback>
  </Avatar>
  <Avatar>
    <AvatarImage src="/docs/avatar/lr.png" alt="LR" />
    <AvatarFallback>LR</AvatarFallback>
  </Avatar>
  <Avatar>
    <AvatarImage src="/docs/avatar/er.png" alt="ER" />
    <AvatarFallback>ER</AvatarFallback>
  </Avatar>
  <AvatarGroupCount>+3</AvatarGroupCount>
</AvatarGroup>

Group with icon

You can also pass an icon as the AvatarGroupCount child.

CNLRER

<AvatarGroup aria-label="Team">
  <Avatar>
    <AvatarImage src="/docs/avatar/cn.png" alt="CN" />
    <AvatarFallback>CN</AvatarFallback>
  </Avatar>
  <Avatar>
    <AvatarImage src="/docs/avatar/lr.png" alt="LR" />
    <AvatarFallback>LR</AvatarFallback>
  </Avatar>
  <Avatar>
    <AvatarImage src="/docs/avatar/er.png" alt="ER" />
    <AvatarFallback>ER</AvatarFallback>
  </Avatar>
  <AvatarGroupCount>
    <PlusIcon />
  </AvatarGroupCount>
</AvatarGroup>

Sizes

Use the size prop on the root avatar.

CNCNCN

<Avatar size="sm">
  <AvatarImage src="/docs/avatar/cn.png" alt="CN" />
  <AvatarFallback>CN</AvatarFallback>
</Avatar>
<Avatar>
  <AvatarImage src="/docs/avatar/cn.png" alt="CN" />
  <AvatarFallback>CN</AvatarFallback>
</Avatar>
<Avatar size="lg">
  <AvatarImage src="/docs/avatar/cn.png" alt="CN" />
  <AvatarFallback>CN</AvatarFallback>
</Avatar>

Accessibility

Avatar is presentational. The image, fallback, badge, and group need names so the control stays readable without the photo.

Name the image

Give AvatarImage an alt that names the person. Always keep AvatarFallback so initials remain if the image fails.

<Avatar>
  <AvatarImage src="/docs/avatar/cn.png" alt="CN" />
  <AvatarFallback>CN</AvatarFallback>
</Avatar>

Label status badges

An empty badge is only a color. Add aria-label for the status it represents. For clickable actions, compose the badge onto a button with render or asChild so keyboard and focus work.

<AvatarBadge aria-label="Online" />
<AvatarBadge
  aria-label="Add teammate"
  render={<button type="button" />}
>
  <PlusIcon />
</AvatarBadge>

Label the group

AvatarGroup renders role="group". Give it an aria-label that describes the set of people.

<AvatarGroup aria-label="Team">
  <Avatar>
    <AvatarImage src="/docs/avatar/cn.png" alt="CN" />
    <AvatarFallback>CN</AvatarFallback>
  </Avatar>
</AvatarGroup>

RTL

To enable RTL support, see the Direction guide.

CNER

CNLRER

<div
  dir="rtl"
  className="flex flex-row flex-wrap items-center gap-6 md:gap-12"
>
  <Avatar>
    <AvatarFallback>CN</AvatarFallback>
  </Avatar>
  <Avatar>
    <AvatarFallback>ER</AvatarFallback>
    <AvatarBadge
      aria-label="Online"
      className="bg-green-600 dark:bg-green-800"
    />
  </Avatar>
  <AvatarGroup aria-label="Team">
    <Avatar>
      <AvatarFallback>CN</AvatarFallback>
    </Avatar>
    <Avatar>
      <AvatarFallback>LR</AvatarFallback>
    </Avatar>
    <Avatar>
      <AvatarFallback>ER</AvatarFallback>
    </Avatar>
  </AvatarGroup>
</div>

API Reference

Note: Always provide AvatarFallback so the control stays readable when the image is missing.

Avatar

The root that wraps the image, fallback, and optional badge.

Prop	Type	Default	Description
size	"default" \| "sm" \| "lg"	"default"	The size of the avatar.
className	string	-	Additional Tailwind classes merged with the component styles (last one wins).

AvatarImage

The photo. Hidden automatically when it fails to load.

Prop	Type	Default	Description
src	string	-	Image URL. When it fails to load, the fallback is shown.
alt	string	-	Required accessible name for the person in the image.
className	string	-	Additional Tailwind classes merged with the component styles (last one wins).

AvatarFallback

Initials or an icon shown while the image loads or after it fails.

Prop	Type	Default	Description
delay	number	0	Milliseconds to wait before showing the fallback while the image loads.
className	string	-	Additional Tailwind classes merged with the component styles (last one wins).
children	React.ReactNode	-	Usually initials shown when the image is missing.

AvatarBadge

A status indicator at the end of the avatar. Compose onto a button when the badge is an action.

Prop	Type	Default	Description
render	React.ReactElement	-	Render the badge as another element, such as a button, for real actions. On Radix, use asChild instead.
className	string	-	Additional Tailwind classes merged with the component styles (last one wins).
children	React.ReactNode	-	Optional icon inside the badge. Empty badges are status dots.
aria-label	string	-	Name for a status or action when the badge has no text.

AvatarGroup

Overlapping avatars for a set of people.

Prop	Type	Default	Description
className	string	-	Additional Tailwind classes merged with the component styles (last one wins).
children	React.ReactNode	-	Avatar items, optionally followed by AvatarGroupCount.
aria-label	string	-	Name for the group. Required when the group is a set of people.

AvatarGroupCount

Overflow count or icon after the stacked avatars.

Prop	Type	Default	Description
className	string	-	Additional Tailwind classes merged with the component styles (last one wins).
children	React.ReactNode	-	Overflow count text such as +3, or an icon.