Avatar
A versatile and customizable avatar component with support for images, fallbacks, and grouped displays.
Basic Avatar
With image and fallback
Fallback Only
When image fails to load
Avatar Group
Standard overlapping avatars
Hover Scale Effect
Hover over avatars to see effect
Installation
Quickly add the component using:
File Structure
Here’s the file structure for the Avatar component:
Basic Examples
Basic Avatar
Basic Avatar
With image and fallback
Avatar with Fallback
Fallback Only
When image fails to load
Avatar Group
Avatar Group
Standard overlapping avatars
Avatar Group with Hover Scale
Hover Scale Effect
Hover over avatars to see effect
Customization Options
Different Sizes
Different Shapes
Styled Avatars
Real-world Use Cases
User Profile
John Doe
Senior Developer
Team Members
Project Team
5 membersProps
The Avatar component and its subcomponents (AvatarImage, AvatarFallback, and AvatarGroup) offer extensive customization. Here’s a breakdown of their props:
Avatar Props
| Prop | Type | Default |
|---|---|---|
className | string | - |
AvatarImage Props
| Prop | Type | Default |
|---|---|---|
src | string | - |
alt | string | - |
className | string | - |
AvatarFallback Props
| Prop | Type | Default |
|---|---|---|
className | string | - |
children | React.ReactNode | - |
delayMs | number | 600 |
AvatarGroup Props
| Prop | Type | Default |
|---|---|---|
overlap | string | "-ml-2" |
hoverScale | boolean | false |
limit | number | - |
totalCount | number | - |
className | string | - |
Features
The enhanced Avatar component provides the following features:
- Customizable Display:
- Supports images, initials, or any fallback content
- Configurable sizes from extra small to extra large
- Multiple shape options including circle, rounded, and square
- Styling options with borders, rings, shadows, and gradients
- Grouped Avatars:
- Overlapping display with configurable spacing
- Optional hover scale effects for interactive experience
- Automatic “more” indicator for groups exceeding size limits
- Group count display for large teams
- Responsive Design:
- Automatically adjusts to container sizes
- Maintains image aspect ratios
- Ensures crisp display at all sizes
- Accessible Design:
- Required alt text for images
- Meaningful fallback content
- Screen reader support
- Proper ARIA attributes
Best Practices
When using the Avatar component:
-
Image Quality: Use appropriately sized images to prevent blurry avatars. Ideally, image resolution should be at least 2x the displayed size.
-
Fallback Text: Keep fallback text to 2-3 characters maximum for best appearance. Typically, use initials for a person.
-
Group Limits: For AvatarGroup, limit visible avatars to 5-7 and use the limit prop to show a count for larger groups.
-
Accessibility: Always provide meaningful alt text for AvatarImage that identifies the person or entity represented.
Common Patterns
The Avatar component can be used in various UI patterns:
- Comments & Discussions: Show author avatars next to their contributions
- Team Directories: Display member images in a searchable directory
- User Cards: Include avatars as part of user profile cards or hover cards
- Message Systems: Show sender/receiver avatars in chat applications
- Collaborative Platforms: Indicate who is currently viewing or editing content
- Activity Feeds: Include user avatars with activity notifications
Accessibility
The Avatar component is designed with accessibility in mind:
- Alt Text: Required alt attribute ensures screen readers can identify the avatar image
- Fallback Content: Provides meaningful alternatives when images fail to load
- Contrast: Default styles maintain proper contrast ratios for text legibility
- Keyboard Navigation: Fully navigable when used within interactive contexts
- ARIA Support: Leverages Radix UI’s built-in ARIA attributes for proper screen reader support
When using custom colors, ensure text within fallbacks maintains a minimum contrast ratio of 4.5:1 for small text or 3:1 for large text to keep the component accessible.
Conclusion
The enhanced Avatar component provides a comprehensive solution for displaying user or entity images in your Next.js applications. With support for various sizes, shapes, grouping options, and robust fallbacks, it offers both flexibility and reliability.
Its integration with Radix UI primitives ensures accessibility, while the customizable styling options allow seamless integration with your application’s design system. The additional features like group limits, hover effects, and enhanced fallbacks make it suitable for advanced use cases beyond basic profile pictures.
Whether you’re building a social platform, team collaboration tool, or any user-centric interface, the Avatar component provides a solid foundation that balances visual appeal with technical functionality.