Skip to main content

​
Overview

AD
Online
RM
Away
+2
Avatar displays a user’s profile image or their initials when no image is available. It supports five sizes, circle and square shapes, status indicators, and grouped stacks.

​
Installation

​
Usage

​
Variants

​
Sizes

​
With Status Indicator

​
Square Shape

AD
LG

​
Avatar Group

+2

​
API Reference

​
Avatar

​
string
Image URL. Falls back to fallback initials if the image fails to load.
​
string
Alt text for the image element.
​
string
Initials shown when the image is unavailable (e.g. "AD").
​
string
default:"md"
Avatar size. Values: xs · sm · md · lg · xl
​
string
default:"circle"
Border radius variant. Values: circle · square
​
string
Status indicator dot color. Values: online · away · busy · offline
​
boolean
default:"false"
Shows a ring border around the avatar.
​
string
Additional Tailwind classes for custom overrides.

​
AvatarGroup

​
number
Maximum avatars to show before displaying an overflow count.
​
string
default:"md"
Applies uniformly to all avatars in the group.

​
Accessibility

  • Avatar image uses an <img> element with alt text
  • When no image is provided, role="img" and aria-label are set with the fallback value
  • Status indicators have aria-label describing the status (e.g. “Online”)
  • AvatarGroup overflow count uses aria-label like “+2 more users”

​
Do’s & Don’ts

Do

  • Always provide alt text for avatars with images
  • Use fallback initials as a graceful degradation
  • Use AvatarGroup with max to cap the visible stack
  • Match avatar size to the surrounding content density

Don't

  • Don’t use avatars as clickable buttons without additional affordance
  • Don’t show status indicators unless the status is live and meaningful
  • Don’t use more than 5 stacked avatars without overflow count
  • Don’t crop logos or brand icons in circular avatars — use square shape