Avatar

Visual representation of a user or entity. Supports images, initials fallback, and icon fallback with multiple sizes and shapes.

With Image

With Initials

Icon Fallback

Sizes

Shapes

In Context

John Doe

john@example.com

Props

Name	Type	Default	Description
`src`	`string`	-	Image URL
`alt`	`string`	-	Alt text for image
`fallback`	`string`	-	Name for initials fallback
`size`	`'sm' \| 'md' \| 'lg' \| 'xl'`	`'md'`	Avatar size
`shape`	`'circle' \| 'square'`	`'circle'`	Avatar shape
`className`	`string`	-	Additional CSS classes

Fallback Behavior

The Avatar component has a three-tier fallback system:

Image: If src is provided and loads successfully
Initials: If image fails or fallback name is provided
Icon: If no image or fallback name is available

Usage Guidelines

When to use

•For user profiles and account menus
•For comment threads and activity feeds
•For team member lists
•For contact lists

Best practices

•Always provide descriptive alt text for images
•Use fallback for better UX when images fail to load
•Use circle shape for user avatars (default)
•Use square shape for organizations or brands
•Match size to context (sm for lists, lg for profiles)
•Ensure consistent sizing in lists

Accessibility

•Images include alt text for screen readers
•Initials are readable text, not background images
•Icon fallback uses semantic SVG with proper aria labels
•Sufficient color contrast for initials on background

Do's and Don'ts

✓ Do

•Use circle shape for user avatars
•Provide fallback names for initials
•Use consistent sizes in lists
•Include descriptive alt text

Sarah Johnson

Designer

✗ Don't

•Mix different sizes in the same list
•Use generic alt text like "avatar" or "profile"
•Use square avatars for people
•Leave alt text empty when using images

Related Components

Badge

Use badges with avatars to show status or notifications

Button

Combine avatars with buttons for user action menus

Card

Display avatars within cards for user profiles