Avatar
A circular (or rounded) user avatar that displays a profile image, 1–2 character initials, or a fallback icon. Supports six sizes, six initials color variants, an optional Status dot at any corner, full RTL layout, and an AvatarGroup for stacking.
Playground
Installation
pnpm add @tessinaui/uiUsage
import { Avatar, AvatarGroup } from "@tessinaui/ui";{/* Image */}
<Avatar src="/avatar.jpg" alt="Jane Doe" />
{/* Initials */}
<Avatar initials="JD" />
{/* With status */}
<Avatar src="/avatar.jpg" alt="Jane Doe" status="online" />Examples
Default
A basic image avatar with accessible alt text.
Fallbacks
Falls back from image to initials to a generic User icon when no source is provided.
Sizes
Six sizes — xs, sm, md, lg, xl, and 2xl.
Colors
Six initials background colors — default, primary, error, warning, success, and info.
With Status
A status dot that auto-scales to the avatar and sits in the corner.
Group
Stack overlapping avatars with a +N overflow badge past max.
API Reference
Avatar Props
| Prop | Type | Default | Description |
|---|---|---|---|
src | string | — | Profile image URL. When set, the image fills the avatar and color is ignored |
alt | string | "" | Accessible alt text for the image |
initials | string | — | 1–2 characters shown when no src. Automatically uppercased and truncated to 2 chars |
size | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "lg" | Diameter: 20 / 24 / 32 / 40 / 56 / 64 px |
rounded | "full" | "xl" | "lg" | "md" | "sm" | "none" | "full" | Border radius of the avatar container |
color | "default" | "primary" | "error" | "warning" | "success" | "info" | "default" | Background color for initials / fallback. Ignored when src is provided |
status | StatusProps["variant"] | — | Status dot variant — see Status for the full list |
statusPosition | "top-right" | "top-left" | "bottom-right" | "bottom-left" | "top-right" in LTR, "top-left" in RTL | Corner where the status dot appears |
dir | "ltr" | "rtl" | "ltr" | Text direction. Changes the default statusPosition: LTR → top-right, RTL → top-left |
showIconFallback | boolean | true | Show a User icon when neither src nor initials is provided |
className | string | — | Extra classes on the container <span> |
All other native <span> attributes are forwarded.
AvatarGroup Props
| Prop | Type | Default | Description |
|---|---|---|---|
max | number | 5 | Maximum visible avatars before showing a +N overflow badge |
size | same as Avatar | "lg" | Applied to all child Avatars |
rounded | same as Avatar | "full" | Applied to all child Avatars |
dir | "ltr" | "rtl" | "ltr" | Stack direction. LTR overlaps left-to-right, RTL right-to-left |
Sizes
| Size | Diameter | Initials text | Status size |
|---|---|---|---|
xs | 20 px | 9 px | xs (8 px) |
sm | 24 px | 10 px | xs (8 px) |
md | 32 px | 12 px | sm (12 px) |
lg | 40 px | 14 px | md (16 px) |
xl | 56 px | 20 px | lg (20 px) |
2xl | 64 px | 24 px | xl (24 px) |
With Status
The status dot auto-scales to the correct size for each avatar and adds a ring-2 ring-background white ring to visually separate it from the avatar:
<Avatar src="/avatar.jpg" alt="Jane" status="online" />
<Avatar src="/avatar.jpg" alt="Jane" status="away" />
<Avatar src="/avatar.jpg" alt="Jane" status="busy" />Override the corner position:
<Avatar src="/avatar.jpg" status="online" statusPosition="bottom-right" />RTL
Pass dir="rtl" to flip the status dot to the top-left corner by default:
<Avatar src="/avatar.jpg" status="online" dir="rtl" />
{/* Explicit override in RTL */}
<Avatar src="/avatar.jpg" status="online" dir="rtl" statusPosition="bottom-left" />AvatarGroup
<AvatarGroup max={4}>
<Avatar src="/user1.jpg" alt="User 1" />
<Avatar src="/user2.jpg" alt="User 2" />
<Avatar src="/user3.jpg" alt="User 3" />
<Avatar src="/user4.jpg" alt="User 4" />
<Avatar src="/user5.jpg" alt="User 5" />
<Avatar initials="AB" />
</AvatarGroup>RTL group (stack direction flips):
<AvatarGroup dir="rtl" max={3}>
<Avatar src="/user1.jpg" alt="User 1" />
<Avatar src="/user2.jpg" alt="User 2" />
<Avatar src="/user3.jpg" alt="User 3" />
<Avatar initials="أب" />
</AvatarGroup>Accessibility
- Image avatars:
<img>with the providedalttext - Initials avatars:
aria-hiddenon the text span; setaria-labelon the container for screen readers - Fallback icon:
aria-hidden - Status dot:
role="img" aria-label="{variant}"— see Status - Touch targets: minimum 44×44 px at
lgand above; at smaller sizes wrap in a tappable element if needed
AspectRatio
Constrains content to a specific width/height ratio using CSS aspect-ratio. Seven named presets, arbitrary string or numeric ratios, eight corner-radius presets, automatic object-fit on single media children, and polymorphic render.
Badge
A small notification indicator that overlays other components. Two variants — Dot (plain circle) and Label (pill with text). Two appearances — Solid and Outline. Four sizes. Six colors. Five corner-rounding options.