baseui-cnAvatar
An image element with a fallback for representing the user.
Installation
npx baseui-cn add avatarUsage
import {
Avatar,
AvatarBadge,
AvatarFallback,
AvatarGroup,
AvatarGroupCount,
AvatarImage,
} from "@/components/ui/avatar"<Avatar size="md">
<AvatarImage src="/photo.jpg" alt="Aria Chen" />
<AvatarFallback>AC</AvatarFallback>
<AvatarBadge className="bg-success" />
</Avatar>Examples
Basic
An avatar with fallback initials.
With image
Image avatars fall back to initials when the image is unavailable.
Image sizes
Use xs, sm, md, and lg to keep avatars aligned with nearby controls and cards.
With badge
Status badges use your theme tokens so online and away states still feel native to the app.
Group
Stack avatars together and add an overflow count when you do not want to render every participant.
Sizes
The core avatar supports xs, sm, md, and lg sizing for denser or roomier layouts.
Image group
The grouped pattern also works with uploaded images and mixed fallbacks.
API
Avatar
| Prop | Type | Default | Description |
|---|---|---|---|
size | "xs" | "sm" | "md" | "lg" | "md" | Diameter of the avatar circle and font size of the fallback initials |
showBadge | boolean | false | Render a presence/status badge overlay on the avatar |
badgeVariant | "online" | "offline" | "busy" | "away" | "online" | Color of the presence badge (requires showBadge) |
badgePosition | "top-right" | "top-left" | "bottom-right" | "bottom-left" | "top-right" | Corner placement of the badge |
AvatarBadge
Use AvatarBadge directly for fine-grained control over the badge separately from Avatar.
| Prop | Type | Default | Description |
|---|---|---|---|
variant | "online" | "offline" | "busy" | "away" | "online" | Presence status color |
badgePosition | "top-right" | "top-left" | "bottom-right" | "bottom-left" | "top-right" | Corner placement |
AvatarGroupCount
| Prop | Type | Default | Description |
|---|---|---|---|
size | "xs" | "sm" | "md" | "lg" | "md" | Diameter to match the rest of the avatar group |
API Reference
See the Base UI Avatar documentation for the full API reference, including all props, data attributes, and CSS classes.