Avatar

A user identity component for displaying profile images, initials, or icon fallbacks with status indicators and group stacking.

Basic

A user identity component for displaying profile images, initials, or icon fallbacks. Supports status indicators, 5 sizes, 2 shapes, and group stacking.

ACBSCDDEEF

ACBSCDDE

<Avatar name="Alice Cooper" size="xs" />
<Avatar name="Bob Smith" size="sm" />
<Avatar name="Charlie Davis" size="md" />
<Avatar name="Diana Evans" size="lg" />
<Avatar name="Evan Foster" size="xl" />

<Avatar name="Alice Cooper" status="online" />
<Avatar name="Bob Smith" status="busy" />
<Avatar name="Charlie Davis" status="away" />
<Avatar name="Diana Evans" status="offline" />

<Avatar name="Alice Cooper" size="xs" /><Avatar name="Bob Smith" size="sm" /><Avatar name="Charlie Davis" size="md" /><Avatar name="Diana Evans" size="lg" /><Avatar name="Evan Foster" size="xl" /><Avatar name="Alice Cooper" status="online" /><Avatar name="Bob Smith" status="busy" /><Avatar name="Charlie Davis" status="away" /><Avatar name="Diana Evans" status="offline" />

Installation

Install the component via the CLI in one command.

npx @work-rjkashyap/unified-ui add avatar

pnpm dlx @work-rjkashyap/unified-ui add avatar

npx @work-rjkashyap/unified-ui add avatar

bunx @work-rjkashyap/unified-ui add avatar

If you haven't initialized your project yet, run npx @work-rjkashyap/unified-ui init first. See the CLI docs for details.

Or install the full package

Use this approach if you prefer to install the entire design system as a dependency instead of copying individual components.

npm install @work-rjkashyap/unified-ui

pnpm add @work-rjkashyap/unified-ui

yarn add @work-rjkashyap/unified-ui

bun add @work-rjkashyap/unified-ui

Anatomy

import {
	Avatar,
	AvatarGroup,
} from "@work-rjkashyap/unified-ui";

Basic Usage

The Avatar component displays a user image. When no src is provided (or the image fails to load), it falls back to initials derived from the name prop, or a default user icon.

// With image
<Avatar src="/photo.jpg" alt="Jane Doe" />

// With initials fallback
<Avatar name="Jane Doe" />

// Default icon fallback (no name or src)
<Avatar />

Sizes

Five sizes are available ranging from extra small (24px) to extra large (64px).

XSMLX

<Avatar name="Jane" size="xs" />  {/* 24px */}
<Avatar name="Jane" size="sm" />  {/* 32px */}
<Avatar name="Jane" size="md" />  {/* 40px — default */}
<Avatar name="Jane" size="lg" />  {/* 48px */}
<Avatar name="Jane" size="xl" />  {/* 64px */}

<Avatar name="Jane" size="xs" />  {/* 24px */}<Avatar name="Jane" size="sm" />  {/* 32px */}<Avatar name="Jane" size="md" />  {/* 40px — default */}<Avatar name="Jane" size="lg" />  {/* 48px */}<Avatar name="Jane" size="xl" />  {/* 64px */}

Size	Dimensions	Use Case
`xs`	24×24px	Inline mentions, compact lists
`sm`	32×32px	Comment threads, table rows
`md`	40×40px	Default, navigation bars
`lg`	48×48px	Profile cards, headers
`xl`	64×64px	Profile pages, hero sections

Shapes

Two shapes are supported: circle (default) and square.

<Avatar name="Jane Doe" shape="circle" />  {/* Default */}
<Avatar name="Jane Doe" shape="square" />  {/* Rounded square */}

<Avatar name="Jane Doe" shape="circle" />  {/* Default */}<Avatar name="Jane Doe" shape="square" />  {/* Rounded square */}

Initials Fallback

When no src is provided (or the image fails to load), the component automatically generates initials from the name prop. It takes the first letter of the first and last words.

JDABS

<Avatar name="Jane Doe" />      {/* Shows "JD" */}
<Avatar name="Alice" />          {/* Shows "A" */}
<Avatar name="Bob Charles Smith" /> {/* Shows "BS" */}

<Avatar name="Jane Doe" />      {/* Shows "JD" */}<Avatar name="Alice" />          {/* Shows "A" */}<Avatar name="Bob Charles Smith" /> {/* Shows "BS" */}

Status Indicator

Add a status prop to display a small colored dot indicating the user's availability.

OBAO

<Avatar name="Jane" status="online" />   {/* Green dot */}
<Avatar name="Jane" status="busy" />     {/* Red dot */}
<Avatar name="Jane" status="away" />     {/* Yellow dot */}
<Avatar name="Jane" status="offline" />  {/* Gray dot */}

<Avatar name="Jane" status="online" />   {/* Green dot */}<Avatar name="Jane" status="busy" />     {/* Red dot */}<Avatar name="Jane" status="away" />     {/* Yellow dot */}<Avatar name="Jane" status="offline" />  {/* Gray dot */}

Status	Color	Meaning
`online`	Green (`--success`)	User is active
`busy`	Red (`--danger`)	User is unavailable
`away`	Yellow (`--warning`)	User is idle
`offline`	Gray (`--muted`)	User is offline

Avatar Group

Use AvatarGroup to stack multiple avatars with a configurable overlap. When the number of avatars exceeds the max prop, a "+N" overflow indicator is shown.

ACBSCD+2

<AvatarGroup max={3}>
<Avatar name="Alice Cooper" />
<Avatar name="Bob Smith" />
<Avatar name="Charlie Davis" />
<Avatar name="Diana Evans" />
<Avatar name="Evan Foster" />
</AvatarGroup>
{/* Shows Alice, Bob, Charlie, then "+2" */}

<AvatarGroup max={3}><Avatar name="Alice Cooper" /><Avatar name="Bob Smith" /><Avatar name="Charlie Davis" /><Avatar name="Diana Evans" /><Avatar name="Evan Foster" /></AvatarGroup>{/* Shows Alice, Bob, Charlie, then "+2" */}

Group with Images

ABCD+2

<AvatarGroup max={4}>
<Avatar src="/a.jpg" alt="Alice" />
<Avatar src="/b.jpg" alt="Bob" />
<Avatar src="/c.jpg" alt="Charlie" />
<Avatar src="/d.jpg" alt="Diana" />
<Avatar src="/e.jpg" alt="Evan" />
<Avatar src="/f.jpg" alt="Fiona" />
</AvatarGroup>

<AvatarGroup max={4}><Avatar src="/a.jpg" alt="Alice" /><Avatar src="/b.jpg" alt="Bob" /><Avatar src="/c.jpg" alt="Charlie" /><Avatar src="/d.jpg" alt="Diana" /><Avatar src="/e.jpg" alt="Evan" /><Avatar src="/f.jpg" alt="Fiona" /></AvatarGroup>

Image Error Handling

When a src is provided but the image fails to load, the Avatar gracefully falls back to initials (if name is set) or the default icon.

{/* If image fails, shows "JD" */}
<Avatar src="/broken-link.jpg" name="Jane Doe" />

{/* If image fails and no name, shows default user icon */}

<Avatar src="/broken-link.jpg" alt="User" />

{/* If image fails, shows "JD" */}<Avatar src="/broken-link.jpg" name="Jane Doe" />{/* If image fails and no name, shows default user icon */}<Avatar src="/broken-link.jpg" alt="User" />

With Alt Text

Always provide descriptive alt text for images via the alt prop, or use the name prop which doubles as accessible text.

JDJD

{/* alt text from alt prop */}
<Avatar src="/photo.jpg" alt="Jane Doe's profile picture" />

{/* alt text from name prop */}

<Avatar name="Jane Doe" />

{/* alt text from alt prop */}<Avatar src="/photo.jpg" alt="Jane Doe's profile picture" />{/* alt text from name prop */}<Avatar name="Jane Doe" />

Props

Prop	Type	Default	Description
`src`	`string`	—	URL of the avatar image.
`alt`	`string`	—	Alt text for the image. Falls back to `name` if not provided.
`name`	`string`	—	User name used to generate initials fallback.
`size`	`"xs" \| "sm" \| "md" \| "lg" \| "xl"`	`"md"`	Size of the avatar.
`shape`	`"circle" \| "square"`	`"circle"`	Shape of the avatar.
`status`	`"online" \| "offline" \| "busy" \| "away"`	—	Status indicator dot.
`className`	`string`	—	Additional CSS classes.

AvatarGroup

Prop	Type	Default	Description
`max`	`number`	—	Maximum number of avatars to display before showing "+N".
`size`	`"xs" \| "sm" \| "md" \| "lg" \| "xl"`	`"md"`	Size applied to all child avatars.
`className`	`string`	—	Additional CSS classes.

Accessibility

Images include an alt attribute (falls back to name if alt is not provided).
Initials fallback uses role="img" with an aria-label derived from name.
Status indicators have an aria-label describing the status (e.g., "online").
The status dot itself is decorative — the accessible label is on the parent element.
The "+N" overflow indicator in AvatarGroup is announced to screen readers.

Design Tokens

Token	Usage
`--muted`	Initials/icon fallback background
`--success`	Online status indicator
`--danger`	Busy status indicator
`--warning`	Away status indicator
`--radius-full`	Circle shape
`--radius-md`	Square shape border radius

Avatar

On this page