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

npm install @araf-ds/core

​
Usage

import { Avatar, AvatarGroup } from "@araf-ds/core"

export default function Example() {
  return (
    <Avatar
      src="/photo.jpg"
      fallback="AD"
      size="md"
      status="online"
    />
  )
}

​
Variants

​
Sizes

<Avatar size="xs" fallback="AD" />
<Avatar size="sm" fallback="AD" />
<Avatar size="md" fallback="AD" />
<Avatar size="lg" fallback="AD" />
<Avatar size="xl" fallback="AD" />
SizeDiameterUse case
xs20pxDense lists, tables
sm28pxCompact cards
md36pxDefault — sidebars, headers
lg48pxProfile sections
xl64pxFull profile pages

​
With Status Indicator

<Avatar fallback="AD" size="md" status="online" />
<Avatar fallback="RM" size="md" status="away" />
<Avatar fallback="JS" size="md" status="busy" />
<Avatar fallback="ZK" size="md" status="offline" />

​
Square Shape

AD
LG
<Avatar fallback="AD" shape="square" size="md" />
<Avatar fallback="AD" shape="square" size="lg" />

​
Avatar Group

+2
<AvatarGroup max={4} size="sm">
  <Avatar src="/user1.jpg" fallback="A1" />
  <Avatar src="/user2.jpg" fallback="A2" />
  <Avatar src="/user3.jpg" fallback="A3" />
  <Avatar src="/user4.jpg" fallback="A4" />
  <Avatar src="/user5.jpg" fallback="A5" />
  <Avatar src="/user6.jpg" fallback="A6" />
  {/* +2 overflow shown automatically */}
</AvatarGroup>

​
API Reference

​
Avatar

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

​
AvatarGroup

​
max
number
Maximum avatars to show before displaying an overflow count.
​
size
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