Avatar

Design checklist

Anatomy

The Avatar component consists of three main variants - standard Avatar, AvatarGroup, and AvatarTrigger - each with their own specific anatomical elements.

Avatar

The standard Avatar contains:

• Container: A circular container that holds the avatar content
• Content: Can be one of:
  • Image: User photo or entity image
  • Initials: Text representing user's initials
  • Placeholder icon: Default icon when no image or initials are provided
• Status indicator: Optional visual indicator showing user status
  • Dot: A small colored circle positioned at the edge of the avatar
  • Border: A colored outline surrounding the avatar
• Border: Optional decorative or functional border around the avatar

AvatarGroup

The AvatarGroup combines multiple avatars:

• Container: Groups and positions multiple avatars
• Avatars: Individual avatar components
• Overflow indicator: Appears when there are more avatars than can be displayed
  • Count: Shows how many additional avatars are not displayed
  • Background: Uses the avatar styling but contains the count

AvatarTrigger

The AvatarTrigger extends the standard Avatar with:

• Interactive state: Visual feedback for hover, focus, and active states
• Active indicator: Shows when the avatar is in an active/selected state

States

Avatars can exist in various states that communicate status and interaction feedback.

Image states

• Default: Shows the provided image
• Error/Fallback: When image fails to load, shows initials or placeholder icon
• Loading: While image is loading (handled automatically by Next.js Image component)

Interaction states (AvatarTrigger)

• Default: Normal appearance
• Hover: Visual feedback when pointer is over the avatar
• Focus: Visual indication when focused via keyboard
• Active: Visual indication when avatar is clicked/pressed
• Selected: When the avatar represents selected state
• Disabled: When interaction is not available

Status states

• No status: Default state with no status indicator
• Status dot: Shows a colored dot indicator
  • Static: Solid color indicator
  • Pulse: Animated pulsing indicator for attention
• Status border: Shows a colored border around the avatar
  • Static: Solid color border
  • Pulse: Animated pulsing border for attention

Options

Avatars provide various options for customization:

Size

Six predefined sizes allow for flexibility in different UI contexts:

• 2extra-small (2xs)
• extra-small (xs)
• small (sm)
• medium (md) - default
• large (lg)
• extra-large (xl)

Content types

• Image: src property provides an image URL
• Initials: initials property shows 1-3 characters of text
• Placeholder: Default icon when no image or initials are provided

Status colors

When using status indicators, the following colors are available:

• gray
• orange
• violet
• green
• red
• yellow
• blue
• lime
• cyan

Border styles

• Default: Standard border defined in design system
• Alternative: Secondary border style for contrast contexts
• None: No border

Group display

For AvatarGroup:

• Direction: row (default) or column
• Max display: Control how many avatars to show before overflow
• Spacing: Customize the overlap between avatars
• Custom overflow: Option to provide custom overflow indicator

Behaviors

Image handling

• Avatar automatically handles image loading failures by showing initials or a placeholder icon
• Images maintain aspect ratio inside the circular container with object-fit: cover

AvatarGroup behaviors

• Avatars stack with a negative margin for an overlapping effect
• Direction can be row (horizontal stack) or column (vertical stack)
• Maximum display count limits how many avatars show before displaying an overflow indicator
• Custom overflow rendering allows for specialized overflow indicators

AvatarTrigger behaviors

• Functions as a button that can be clicked to trigger actions
• Provides appropriate accessibility attributes for interactive elements
• Can display an active/selected state to indicate current selection

Accessibility

• Images include appropriate alt text for screen readers
• When no meaningful alt text is available, it uses empty alt to avoid redundant announcements
• Placeholder icons are marked as decorative (aria-hidden)
• AvatarTrigger provides appropriate keyboard interaction patterns

Responsiveness

• Avatars maintain their aspect ratio and circular shape across screen sizes
• AvatarGroup can adjust overflow count based on available space

Changelog