Avatar
User icon with image support and initials fallback. Compose with AvatarGroup for stacks.
Install
Import path
Examples
Stacked group
Overlap avatars with AvatarGroup and cap the overflow with a count.
Badge
Use the AvatarBadge component to add a badge to the avatar. The badge is positioned at the bottom right of the avatar.
Badge with Icon
You can also use an icon inside <AvatarBadge>.
Basic
A basic avatar component with an image and a fallback.
Dropdown
You can use the Avatar component as a trigger for a dropdown menu.
Avatar Group Count
Use <AvatarGroupCount> to add a count to the group.
Avatar Group with Icon
You can also use an icon inside <AvatarGroupCount>.
RTL
Right-to-left layout support for languages such as Arabic and Hebrew.
Translations are AI-generated for demonstration and may be imperfect.
Sizes
Use the size prop to change the size of the avatar.
Anatomy
How the parts compose. Copy this skeleton and fill in the slots.
import { Avatar, AvatarImage, AvatarFallback } from "@codefast/ui/avatar";
<Avatar>
<AvatarImage src="…" alt="…" />
<AvatarFallback>AB</AvatarFallback>
</Avatar>
API reference
Props for each part of the component. All native element props are also forwarded.
Avatar
| Prop | Type | Default | Description |
|---|---|---|---|
| size | "sm" | "default" | "lg" | "default" | Diameter of the avatar. |
AvatarImage / AvatarFallback
The image and the initials shown until (or unless) the image loads.
| Prop | Type | Default | Description |
|---|---|---|---|
| src / alt | string | — | On AvatarImage. AvatarFallback renders when the image is missing. |
AvatarGroup / AvatarGroupCount
| Prop | Type | Default | Description |
|---|---|---|---|
| children | ReactNode | — | Wrap avatars to overlap them; AvatarGroupCount shows the remainder. |
Accessibility
Built to be keyboard-navigable and screen-reader friendly out of the box.
- Always set a meaningful alt on AvatarImage; use the person’s name.
- AvatarFallback initials are decorative — the name should still exist in alt or nearby text.
- The status badge is decorative; convey the same status in text where it matters.
Guidelines
Conventions that keep usage consistent across an app.
Do
- Provide initials as a fallback for every avatar.
- Cap stacked groups with a +N count rather than showing dozens.
Don’t
- Don’t rely on the avatar image alone to identify a user.
- Don’t use colour-only badges to convey critical status.