Avatar

User representation with image, initials fallback, five sizes, and four status indicators. AvatarGroup stacks multiple avatars with an overlap ring.

Preview

JRSPLMDBA

Sizes

Five sizes cover icon-scale (xs), compact lists (sm), standard UI (md), profile cards (lg), and hero sections (xl).

JRxs

JRsm

JRmd

JRlg

JRxl

Status

A dot in the bottom-right corner communicates presence. The dot is sized proportionally and ringed with the surface color to lift it off any background.

SPonline

SPaway

SPbusy

SPoffline

Initials fallback

When no src is provided, initials are derived from the alt prop (first + last word). Pass initials to override.

JRSPAIX

Avatar group

AvatarGroup stacks avatars with a negative margin and a surface-colored ring to separate them visually.

JRSPLMAKDB

Implementation

Avatar is a server component — no client-side state. The status dot and initials derivation are pure rendering logic.

Avatar.tsx

tsx

import { Avatar, AvatarGroup } from "@/components/ui/Avatar";

// Image avatar
<Avatar src="/avatars/jamieson.jpg" alt="Jamieson Rothwell" />

// Initials fallback (derived from alt)
<Avatar alt="Jamieson Rothwell" />        // → JR
<Avatar alt="Claude" initials="AI" />     // → AI (explicit override)

// Sizes
<Avatar alt="Sam Park" size="xs" />
<Avatar alt="Sam Park" size="sm" />
<Avatar alt="Sam Park" size="md" />
<Avatar alt="Sam Park" size="lg" />
<Avatar alt="Sam Park" size="xl" />

// Status indicators
<Avatar alt="Sam Park"    status="online"  />
<Avatar alt="Lena Müller" status="away"    />
<Avatar alt="Dev Bot"     status="busy"    />
<Avatar alt="Amir Karimi" status="offline" />

// Avatar group
<AvatarGroup>
  <Avatar alt="Sam Park"    size="sm" />
  <Avatar alt="Lena Müller" size="sm" />
  <Avatar alt="Amir Karimi" size="sm" />
  <Avatar alt="Dev Bot"     size="sm" />
</AvatarGroup>

Props

Prop	Type	Default	Description
`src`	`string`	—	Image URL. When provided, renders an <img> inside the avatar.
`alt`	`string`	—	Accessible name. Used as the aria-label and to derive initials when src is absent.
`initials`	`string`	—	Explicit 1–2 character override for the fallback initials.
`size`	`"xs" \| "sm" \| "md" \| "lg" \| "xl"`	`"md"`	Controls diameter, font size, and status dot size.
`status`	`"online" \| "offline" \| "away" \| "busy"`	—	Renders a colored dot indicator in the bottom-right corner.

Mobile

Avatars are primarily visual. On mobile, ensure interactive avatar areas meet touch target minimums and that AvatarGroup stacks don't overflow their containers.

9:41

Team

2 online

5 members

Scenario	Guidance
Tap target	If an avatar opens a profile or triggers an action, wrap it in a button with at least 44×44px of tappable area even if the avatar itself is smaller (e.g. sm at 24px).
AvatarGroup on narrow screens	Reduce the visible count or decrease avatar size when the group would overflow its container. Expose the "+N" overflow count rather than clipping silently.
Image loading	On slow mobile connections, avatar images may take time to load. The initials fallback is rendered before the image resolves — ensure the initials + background color always look correct.
Status dots on small sizes	Status dots at xs/sm avatar sizes can become too small to notice. Only show status on md+ avatars, or increase the dot size relative to the avatar.

Accessibility

→Always provide alt — it becomes the aria-label for the avatar container.
→Status dots have aria-label set to the status string ("online", "away", etc.).
→When src is present the inner <img> receives alt; the outer span gets role=img.
→Initials-only avatars are decorative when the user's name is already visible nearby — in that case pass aria-hidden to the avatar.
→AvatarGroup has no semantic role; describe the group with a nearby heading or aria-label on the parent.