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/ui

Usage

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" />

Showcase

All sizes, variants, states, RTL/LTR, and AvatarGroup:

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 provided alt text
Initials avatars: aria-hidden on the text span; set aria-label on 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 lg and above; at smaller sizes wrap in a tappable element if needed

Playground

Installation

pnpm add @tessinaui/ui

Usage

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" />

Showcase

All sizes, variants, states, RTL/LTR, and AvatarGroup:

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 provided alt text
Initials avatars: aria-hidden on the text span; set aria-label on 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 lg and above; at smaller sizes wrap in a tappable element if needed

Avatar

Playground

Installation

Usage

Showcase

API Reference

Avatar Props

AvatarGroup Props

Sizes

With Status

RTL

AvatarGroup

Accessibility

On this page

Avatar

Playground

Installation

Usage

Showcase

API Reference

Avatar Props

AvatarGroup Props

Sizes

With Status

RTL

AvatarGroup

Accessibility

On this page