Avatar

Represent people in threads, sidebars, and member lists. Show an image when available, fall back to initials, and add status or grouped stacks when needed.

tsx

1import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar"23export function Example() {4  return (5    <Avatar>6      <AvatarImage src="/assets/brand/demos/avatars/avatar-1.png" alt="Mina Cho" />7      <AvatarFallback>MC</AvatarFallback>8    </Avatar>9  )10}

Installation

npx @arctis-sh/@arctis-sh/ui@latest add avatar

Usage

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

1<Avatar>2  <AvatarImage src="/assets/brand/demos/avatars/avatar-1.png" alt="Mina Cho" />3  <AvatarFallback>MC</AvatarFallback>4</Avatar>

Composition

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

AvatarGroup
├── Avatar
└── AvatarGroupCount

Use AvatarImage with AvatarFallback; the fallback remains visible until the image loads. AvatarBadge is optional, and the built-in ring keeps overlapping avatars distinct.

Basic

A profile image with initials ready as a fallback.

tsx

1import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar"23export function Example() {4  return (5    <Avatar>6      <AvatarImage src="/assets/brand/demos/avatars/avatar-1.png" alt="Mina Cho" />7      <AvatarFallback>MC</AvatarFallback>8    </Avatar>9  )10}

Fallback

Use initials on their own for invites, placeholders, or people without an image.

MCJBPN

tsx

1import { Avatar, AvatarFallback } from "@/components/ui/avatar"23export function Example() {4  return (5    <div className="flex items-center gap-3">6      <Avatar>7        <AvatarFallback>MC</AvatarFallback>8      </Avatar>9      <Avatar>10        <AvatarFallback>JB</AvatarFallback>11      </Avatar>12      <Avatar>13        <AvatarFallback>PN</AvatarFallback>14      </Avatar>15    </div>16  )17}

Badge

AvatarBadge sits in the bottom-right for presence or status. It is green by default; use className to match your status colors.

tsx

1import {2  Avatar,3  AvatarBadge,4  AvatarFallback,5  AvatarImage,6} from "@/components/ui/avatar"78export function Example() {9  return (10    <Avatar>11      <AvatarImage src="/assets/brand/demos/avatars/avatar-2.png" alt="Jordan Blake" />12      <AvatarFallback>JB</AvatarFallback>13      <AvatarBadge />14    </Avatar>15  )16}

Group with count

Wrap avatars in AvatarGroup to stack them. Set overlap to sm, default, or lg, then add AvatarGroupCount for the remaining total.

EF+5

tsx

1import {2  Avatar,3  AvatarFallback,4  AvatarGroup,5  AvatarGroupCount,6  AvatarImage,7} from "@/components/ui/avatar"89export function Example() {10  return (11    <AvatarGroup>12      <Avatar>13        <AvatarImage src="/assets/brand/demos/avatars/avatar-1.png" alt="Mina Cho" />14        <AvatarFallback>MC</AvatarFallback>15      </Avatar>16      <Avatar>17        <AvatarImage src="/assets/brand/demos/avatars/avatar-2.png" alt="Jordan Blake" />18        <AvatarFallback>JB</AvatarFallback>19      </Avatar>20      <Avatar>21        <AvatarImage src="/assets/brand/demos/avatars/avatar-3.png" alt="Priya Nair" />22        <AvatarFallback>PN</AvatarFallback>23      </Avatar>24      <AvatarGroupCount>+5</AvatarGroupCount>25    </AvatarGroup>26  )27}

Group with icon

AvatarGroupCount also accepts an icon, which works well for invite, add-member, or custom overflow actions.

tsx

1import {2  Avatar,3  AvatarFallback,4  AvatarGroup,5  AvatarGroupCount,6  AvatarImage,7} from "@/components/ui/avatar"89export function Example() {10  return (11    <AvatarGroup>12      <Avatar>13        <AvatarImage src="/assets/brand/demos/avatars/avatar-4.png" alt="Elena Frost" />14        <AvatarFallback>EF</AvatarFallback>15      </Avatar>16      <Avatar>17        <AvatarImage src="/assets/brand/demos/avatars/avatar-5.png" alt="Samir Haddad" />18        <AvatarFallback>SH</AvatarFallback>19      </Avatar>20      <Avatar>21        <AvatarImage src="/assets/brand/demos/avatars/avatar-6.png" alt="Lucia Reyes" />22        <AvatarFallback>LR</AvatarFallback>23      </Avatar>24      <AvatarGroupCount>25        <PlusIcon />26      </AvatarGroupCount>27    </AvatarGroup>28  )29}

Sizes

Set size on Avatar to xs, sm, default, or lg. You can mix sizes for hierarchy and style AvatarGroupCount with className to match.

tsx

1import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar"23export function Example() {4  return (5    <div className="flex items-end gap-3">6      <Avatar size="xs">7        <AvatarImage src="/assets/brand/demos/avatars/avatar-6.png" alt="Lucia Reyes" />8        <AvatarFallback>LR</AvatarFallback>9      </Avatar>10      <Avatar size="sm">11        <AvatarImage src="/assets/brand/demos/avatars/avatar-6.png" alt="Lucia Reyes" />12        <AvatarFallback>LR</AvatarFallback>13      </Avatar>14      <Avatar>15        <AvatarImage src="/assets/brand/demos/avatars/avatar-6.png" alt="Lucia Reyes" />16        <AvatarFallback>LR</AvatarFallback>17      </Avatar>18      <Avatar size="lg">19        <AvatarImage src="/assets/brand/demos/avatars/avatar-6.png" alt="Lucia Reyes" />20        <AvatarFallback>LR</AvatarFallback>21      </Avatar>22    </div>23  )24}

API Reference

Prop	Type	Default
size	"xs" \| "sm" \| "default" \| "lg"	"default"
className	string	—

1<Avatar>2  <AvatarImage src="..." alt="Mina Cho" />3  <AvatarFallback>MC</AvatarFallback>4</Avatar>

AvatarImage

Prop	Type	Default
src	string	—
alt	string	""
className	string	—

1<AvatarImage src="..." alt="Mina Cho" />

AvatarFallback

Prop	Type	Default
className	string	—

1<AvatarFallback>MC</AvatarFallback>

AvatarBadge

Prop	Type	Default
className	string	—

1<Avatar>2  <AvatarImage src="..." alt="Mina Cho" />3  <AvatarFallback>MC</AvatarFallback>4  <AvatarBadge />5</Avatar>

AvatarGroup

Prop	Type	Default
overlap	"sm" \| "default" \| "lg"	"default"
className	string	—

1<AvatarGroup>2  <Avatar>...</Avatar>3  <Avatar>...</Avatar>4</AvatarGroup>

AvatarGroupCount

Prop	Type	Default
className	string	—

1<AvatarGroupCount>+3</AvatarGroupCount>