Skip to main content
The Avatar component displays user profile images with automatic fallback handling, status badges, and group layouts. Built on Base UI Avatar primitives.

​
Import

import { Avatar } from "@kuzenbo/core";

​
Usage

<Avatar size="md">
  <Avatar.Image src="/user.jpg" alt="Sarah Chen" />
  <Avatar.Fallback>SC</Avatar.Fallback>
</Avatar>

​
Anatomy

  • Avatar - Root container with size context
  • Avatar.Image - Profile image with loading states
  • Avatar.Fallback - Fallback content (typically initials)
  • Avatar.Badge - Status indicator badge
  • Avatar.Group - Container for multiple avatars
  • Avatar.GroupCount - Count indicator for overflow avatars

​
Props

​
Avatar

​
size
'xs' | 'sm' | 'md' | 'lg' | 'xl'
default:"md"
Controls the avatar size:
  • xs - Size 5 (20px)
  • sm - Size 6 (24px)
  • md - Size 8 (32px)
  • lg - Size 10 (40px)
  • xl - Size 11 (44px)
​
className
string
Additional CSS classes to apply.

​
Avatar.Image

​
src
string
required
The image source URL.
​
alt
string
required
Alternative text for the image.
​
className
string
Additional CSS classes.

​
Avatar.Fallback

​
children
ReactNode
required
Fallback content, typically user initials.
​
className
string
Additional CSS classes.

​
Avatar.Badge

​
variant
string
Status variant for the badge.
​
className
string
Additional CSS classes.

​
Avatar.Group

​
max
number
Maximum number of avatars to show before using count indicator.
​
className
string
Additional CSS classes.

​
Avatar.GroupCount

​
count
number
required
Number of overflow avatars.
​
className
string
Additional CSS classes.

​
Examples

​
With image

<Avatar size="md">
  <Avatar.Image src="/avatars/sarah.jpg" alt="Sarah Chen" />
  <Avatar.Fallback>SC</Avatar.Fallback>
</Avatar>

​
Fallback only

When no image is provided or loading fails: 
<Avatar size="md">
  <Avatar.Fallback>JD</Avatar.Fallback>
</Avatar>

​
With status badge

<Avatar size="md">
  <Avatar.Image src="/user.jpg" alt="User" />
  <Avatar.Fallback>U</Avatar.Fallback>
  <Avatar.Badge variant="success" />
</Avatar>

​
Different sizes

<div className="flex items-center gap-2">
  <Avatar size="xs">
    <Avatar.Fallback>XS</Avatar.Fallback>
  </Avatar>
  <Avatar size="sm">
    <Avatar.Fallback>SM</Avatar.Fallback>
  </Avatar>
  <Avatar size="md">
    <Avatar.Fallback>MD</Avatar.Fallback>
  </Avatar>
  <Avatar size="lg">
    <Avatar.Fallback>LG</Avatar.Fallback>
  </Avatar>
  <Avatar size="xl">
    <Avatar.Fallback>XL</Avatar.Fallback>
  </Avatar>
</div>

​
Avatar group

Display multiple avatars in a stacked layout: 
<Avatar.Group>
  <Avatar size="md">
    <Avatar.Image src="/user1.jpg" alt="User 1" />
    <Avatar.Fallback>U1</Avatar.Fallback>
  </Avatar>
  <Avatar size="md">
    <Avatar.Image src="/user2.jpg" alt="User 2" />
    <Avatar.Fallback>U2</Avatar.Fallback>
  </Avatar>
  <Avatar size="md">
    <Avatar.Image src="/user3.jpg" alt="User 3" />
    <Avatar.Fallback>U3</Avatar.Fallback>
  </Avatar>
  <Avatar.GroupCount count={5} />
</Avatar.Group>

​
Clickable avatars

<button type="button" onClick={() => console.log("View profile")}>
  <Avatar size="md">
    <Avatar.Image src="/user.jpg" alt="User" />
    <Avatar.Fallback>U</Avatar.Fallback>
  </Avatar>
</button>

​
Data Attributes

  • [data-size] - Reflects the current size
  • [data-slot] - Component identifier (avatar, avatar-image, avatar-fallback)
  • [data-state] - Image loading state (loading, loaded, error)

​
Accessibility

  • Avatar.Image requires alt text for screen readers
  • Fallback content is announced when image fails
  • Sufficient color contrast in fallback backgrounds
  • Border ring provides visual separation
  • Interactive avatars should be wrapped in button/link elements

​
Base UI Integration

Avatar uses Base UI’s Avatar primitive for:
  • Automatic image loading states
  • Fallback content when image fails or is loading
  • Proper ARIA attributes
  • State management for image lifecycle
The component automatically shows fallback content while the image loads and when loading fails.

Build docs developers (and LLMs) love

Get started for freeTalk to us