How to Use
Avatar
Avatar represents a user or entity with an image, initials, or a fallback icon. Pass a name prop to auto-generate initials from the first and last words. Pass a src prop to show an image. Avatars come in xl, lg, md, sm, and xs sizes. Use them in user profile headers, comment threads, teammate lists, and anywhere you need to identify a person visually. The avatar automatically generates a background color based on the name for visual distinction between different users.
User Avatars with Initials
The simplest usage is passing a name. The Avatar extracts the first letter of the first and last words to generate initials: "John Doe" becomes "JD", "Alice" becomes "A". Each unique name gets a deterministic background color — users with the same name always get the same color, providing consistent visual identification.
<div className="flex items-center gap-4">
<Avatar name="John Doe" />
<Avatar name="Jane Smith" />
<Avatar name="Alice" />
<Avatar name="Bob Wilson" />
</div>Sizes
The size prop controls the avatar's dimensions across a 5-step scale. "xs" (24px) is suited for comment threads and inline user mentions. "sm" (32px) works in table cells and small card headers. "md" (40px) is the default — good for profile sections and list items. "lg" (48px) for profile headers and team grids. "xl" (64px) for hero profiles, account settings, and user profile pages.
<div className="flex items-center gap-3">
<Avatar name="XS" size="xs" />
<Avatar name="SM" size="sm" />
<Avatar name="MD" size="md" />
<Avatar name="LG" size="lg" />
<Avatar name="XL" size="xl" />
</div>Accessibility
Avatar renders with role="img" and an aria-label set to the name prop for screen reader announcements. When using an image src, the avatar renders as an <img> element with the name as alt text. If the image fails to load, the avatar gracefully falls back to showing the generated initials.
Props Reference
All available props for Avatar. See the full API reference page for interactive playground examples.
| Prop | Type | Default | Description |
|---|---|---|---|
| name | string | — | User name used for initials fallback. |
| src | string | — | Image source URL. |
| size | "xs" | "xs-sm" | "sm" | "md" | "lg" | "xl" | "md" | Avatar size. |
| color | "default" | "primary" | "secondary" | "info" | "success" | "warning" | "danger" | "default" | Fallback background color. |
| radius | "none" | "xs" | "xs-sm" | "sm" | "md" | "lg" | "full" | "full" | Border radius. |
| isBordered | boolean | false | Show a border ring. |
| isDisabled | boolean | false | Reduce opacity. |
| icon | ReactNode | — | Custom fallback icon. |
| fallback | ReactNode | — | Custom fallback content. |
Best Practices
- ◆Use size="sm" for comment threads and inline mentions, size="md" for profile sections, size="lg" for profile headers
- ◆Avatar always requires a name prop — this is used for initials generation, background color, and accessibility
- ◆Group avatars in a row with negative margin or gap for team displays, member lists, or collaboration indicators
- ◆For a stacked avatar group (overflow), combine with Badge for online/offline status indicators