Avatar

Visual Hierarchy

Use larger avatars (size-12 or size-16) for profile headers and user detail views. Use the default size (size-8) in lists, comments, and navigation. Use small avatars (size-6) for compact contexts like inline mentions or dense tables.

Spacing & Layout

When placing avatars next to text, use gap-2 for tight layouts or gap-3 for standard spacing. For avatar groups, use -space-x-2 with ring-2 ring-background to create clean overlapping stacks. Limit groups to 3-5 visible avatars plus a count fallback.

Responsive Behavior

Avatar sizes should stay consistent across breakpoints to maintain recognizability. In responsive layouts, consider reducing group count on smaller screens rather than shrinking avatar size. The minimum recommended size is size-6 (24px) to keep initials legible.

Color & Contrast

Fallback backgrounds use bg-muted by default, ensuring sufficient contrast against text-foreground initials. For colored fallbacks, pair semantic tokens like bg-primary with text-primary-foreground to maintain WCAG 2.1 AA compliance. Group ring color should match the page background using ring-background.

Keyboard Navigation

• Tab — Move focus to interactive avatars (links or buttons wrapping avatars)
• Enter — Activate the wrapping interactive element (e.g., open profile)
• Non-interactive avatars are skipped in tab order, which is the expected behavior for decorative elements

Screen Reader Support

• Always provide meaningful alt text on AvatarImage describing the person
• When the user name is displayed adjacent to the avatar, use alt="" to avoid redundant announcements
• Fallback text (initials) is exposed to assistive technology - keep it meaningful
• Interactive avatars wrapped in buttons or links require aria-label on the wrapper

Focus Management

Avatars themselves are not focusable. When used inside interactive wrappers (buttons, links), the focus ring appears on the wrapper element. Ensure the wrapper has a visible focus indicator using focus-visible:ring-[3px] for WCAG 2.1 Level AA compliance.

Image Loading

The Avatar component gracefully degrades: if the image fails to load, AvatarFallback is displayed automatically. Use the delayMs prop on AvatarFallback to prevent flicker during fast connections. Screen readers announce the alt text regardless of whether the image has loaded.

ARIA Attributes

{/* Avatar with descriptive alt text */}
<Avatar>
  <AvatarImage src="/photo.jpg" alt="Jane Doe, Product Manager" />
  <AvatarFallback>JD</AvatarFallback>
</Avatar>

{/* Interactive avatar - requires aria-label */}
<button aria-label="View Jane Doe's profile">
  <Avatar>
    <AvatarImage src="/photo.jpg" alt="" />
    <AvatarFallback>JD</AvatarFallback>
  </Avatar>
</button>

{/* Avatar group with accessible label */}
<div
  role="group"
  aria-label="Team members"
  className="flex -space-x-2 *:data-[slot=avatar]:ring-2 *:data-[slot=avatar]:ring-background"
>
  <Avatar>
    <AvatarImage src="/user1.jpg" alt="Alice Smith" />
    <AvatarFallback>AS</AvatarFallback>
  </Avatar>
  <Avatar>
    <AvatarImage src="/user2.jpg" alt="Bob Jones" />
    <AvatarFallback>BJ</AvatarFallback>
  </Avatar>
</div>

{/* Decorative avatar (alt="" when name is adjacent) */}
<div className="flex items-center gap-2">
  <Avatar>
    <AvatarImage src="/photo.jpg" alt="" />
    <AvatarFallback>JD</AvatarFallback>
  </Avatar>
  <span>Jane Doe</span>
</div>