Avatar

Import

import { Avatar } from '@delightstack/components';

Basic Usage

AJ

View code

<Avatar src="/avatars/alice.jpg" name="Alice Johnson" />

Examples

With Image

<Avatar
  src={user.avatar_url}
  name={user.name}
  size="3"
  status="online"
/>

Initials Fallback

When no src is provided (or the image fails to load), the avatar displays initials derived from the name prop on a deterministic OKLCH-hashed background color.

JD

A

JM

View code

<Avatar name="John Doe" size="2" />
<Avatar name="Alice" size="2" />
<Avatar name="Jean-Pierre Martin" size="2" />

Sizes

Six size presets are available, from inline mentions to hero sections.

A

A

A

A

A

A

View code

<Avatar name="A" size="0" /> <!-- 24px -->
<Avatar name="A" size="1" /> <!-- 32px (default) -->
<Avatar name="A" size="2" /> <!-- 40px -->
<Avatar name="A" size="3" /> <!-- 56px -->
<Avatar name="A" size="4" /> <!-- 80px -->
<Avatar name="A" size="5" /> <!-- 120px -->

Status Indicator

OU

AU

BU

OU

TS

View code

<Avatar name="Online User" status="online" />
<Avatar name="Away User" status="away" />
<Avatar name="Busy User" status="busy" />
<Avatar name="Offline User" status="offline" />

<!-- Status dot on top -->
<Avatar name="Top Status" status="online" status_position="top" />

Badge

DB

CB 5

MN 99+

View code

<!-- Dot indicator -->
<Avatar name="Dot Badge" badge />

<!-- Numeric badge -->
<Avatar name="Count Badge" badge={5} />

<!-- Numbers above 99 display as "99+" -->
<Avatar name="Many Notifications" badge={150} />

Square Shape and Ring

S

R

CR

View code

<Avatar name="Square" square size="3" />
<Avatar name="Ringed" ring size="3" />
<Avatar name="Custom Ring" ring ring_color="red" size="3" />

Interactive Avatar

When onclick is provided, the avatar becomes a focusable button with hover/active states.

<Avatar
  src={user.avatar_url}
  name={user.name}
  onclick={() => openProfile(user)}
/>

With Tooltip

AJ

View code

<Avatar
  name="Alice Johnson"
  tooltip="Alice Johnson - Online"
/>

Skeleton Loading

Show loaded

View code

<Avatar skeleton name={loading ? undefined : 'Ada Lovelace'} size="3" />

Props

Prop	Type	Default	Description
src	string	-	Image URL
name	string	-	Name for initials fallback and auto alt text
size	'0' | '1' | '2' | '3' | '4' | '5'	'1'	Avatar size preset
square	boolean	false	Rounded square shape instead of circle
status	'online' | 'away' | 'busy' | 'offline'	-	Status indicator dot
status_position	'top' | 'bottom'	'bottom'	Status dot position
badge	number | boolean	-	Notification badge (true for dot, number for count)
ring	boolean	false	Show colored ring around avatar
ring_color	string	-	Custom ring color
skeleton	boolean	false	Show a skeleton until the avatar has content — it dismisses itself once the image loads (or immediately when name/children can render)
tooltip	string	''	Tooltip text
onclick	(e: MouseEvent) => void	-	Click handler (makes avatar interactive)
id	string	auto	Element ID
class	string	''	Additional CSS classes
children	Snippet	-	Custom fallback content

Events

Event	Detail	Description
onclick	MouseEvent	Fires when an interactive avatar is clicked

Accessibility

• name prop auto-generates alt text on the image element
• Decorative avatars (no name) use alt=""
• Status indicator has aria-label (e.g., “Online”)
• Badge has aria-label (e.g., “5 notifications”)
• Interactive avatars (with onclick) receive role="button", are focusable, and support Enter/Space activation
• Focus ring is visible on keyboard navigation
• Respects prefers-reduced-motion for pulse animation on online status