Avatar
A flexible avatar component that displays user profile images, initials derived from names with deterministic colors, custom icons, or a default silhouette. Supports 5 sizes, status indicators, rounded variants, and grouping with overflow.
Live Preview
Interact with the Avatar component in real time. Adjust size, rounded, and status to see changes instantly.
<Avatar
src="https://i.pravatar.cc/150?img=1"
alt="Demo User"
name="Demo User"
size="md"
rounded="full"
/>Installation
Install the Aidash Components package using your preferred package manager.
$ pnpm add @aidash/componentsImport
Import the Avatar and AvatarGroup components into your file.
import { Avatar, AvatarGroup } from '@/components/aidash/avatar';Variants
Four content types: image, initials from name, custom icon, and default fallback.
Image
Initials
Icon Fallback
Default (no props)
{/* Image */}
<Avatar src="https://i.pravatar.cc/150?img=1" alt="Sarah Chen" name="Sarah Chen" />
{/* Initials — color is deterministic based on name */}
<Avatar name="Sarah Chen" />
<Avatar name="Alex Rivera" />
{/* Custom icon */}
<Avatar icon={<UserIcon />} name="User" />
{/* Default fallback silhouette */}
<Avatar />Sizes
Five sizes from extra small to extra large to fit any layout context.
1<Avatar src="..." size="xs" /> {/* 24px */}2<Avatar src="..." size="sm" /> {/* 32px */}3<Avatar src="..." size="md" /> {/* 40px — default */}4<Avatar src="..." size="lg" /> {/* 56px */}5<Avatar src="..." size="xl" /> {/* 80px */}Status Indicators
Show user availability with colored status dots positioned at the bottom-right corner.
1<Avatar src="..." status="online" />2<Avatar src="..." status="offline" />3<Avatar src="..." status="away" />4<Avatar src="..." status="busy" />Rounded Variants
Three border-radius options to match different design contexts.
1<Avatar src="..." rounded="full" /> {/* Circle — default */}2<Avatar src="..." rounded="lg" /> {/* rounded-xl */}3<Avatar src="..." rounded="md" /> {/* rounded-lg */}Avatar Group
Stack multiple avatars with overlapping layout and overflow counter using the max prop.
Default Group
With max=3 (overflow)
Initials Group
1{/* Basic group */}2<AvatarGroup>3<Avatar src="..." alt="User 1" />4<Avatar src="..." alt="User 2" />5<Avatar src="..." alt="User 3" />6</AvatarGroup>7 8{/* With max overflow */}9<AvatarGroup max={3}>10<Avatar src="..." alt="User 1" />11<Avatar src="..." alt="User 2" />12<Avatar src="..." alt="User 3" />13<Avatar src="..." alt="User 4" />14<Avatar src="..." alt="User 5" />15{/* Shows +2 overflow counter */}16</AvatarGroup>API Reference
Complete list of props accepted by Avatar and AvatarGroup.
| Prop | Type | Default | Description |
|---|---|---|---|
| src | string | — | Image URL for the avatar |
| alt | string | — | Alt text for the avatar image |
| name | string | — | Name used to generate initials and deterministic background color |
| size | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'md' | Size of the avatar |
| status | 'online' | 'offline' | 'away' | 'busy' | — | Status indicator dot shown at bottom-right |
| icon | ReactNode | — | Custom icon to display when no image or name is provided |
| rounded | 'full' | 'lg' | 'md' | 'full' | Border radius variant |
| className | string | '' | Additional CSS classes |
| Prop | Type | Default | Description |
|---|---|---|---|
| children | ReactNode | — | Avatar components to render in the group |
| max | number | — | Maximum visible avatars; overflow shown as +N counter |
| size | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'md' | Size applied to the overflow counter |
| className | string | '' | Additional CSS classes |
name is provided without src, the avatar displays initials with a deterministic background color based on the name string. The same name always produces the same color.Accessibility
Built-in accessibility features for screen readers and assistive technologies.
Alt Text
Always provide the alt prop when using image avatars. Falls back to name or "Avatar" if not specified.
ARIA Labels on Status
The status indicator dot includes an aria-label attribute with the status value (e.g., "online", "busy") so screen readers can announce availability.
Decorative vs Informative
When the avatar is purely decorative (e.g., next to a visible name), you can omit alt or set it to an empty string. When it conveys identity, always provide a meaningful alt text.
Color Contrast
Initials text uses contrasting foreground colors against the deterministic background. Status indicator colors are distinct and meet WCAG contrast requirements against common surface colors.
1{/* Informative avatar — provide alt text */}2<Avatar src="/photo.jpg" alt="Sarah Chen" name="Sarah Chen" />3 4{/* Decorative avatar next to visible name */}5<div className="flex items-center gap-2">6<Avatar src="/photo.jpg" alt="" name="Sarah Chen" />7<span>Sarah Chen</span>8</div>9 10{/* Status is announced by screen readers */}11<Avatar src="/photo.jpg" alt="Sarah Chen" status="online" />Related
Other components that work well alongside Avatar.