ComponentsFoundations

Avatar

A person or organisation: photo with a locale-correct initials fallback, a colour derived from the name, five sizes, a square shape for logos, a presence dot, and AvatarGroup with a labelled +N overflow.

Radix Avatar components/avatar.tsx, lib/text.ts, styles/forms.csstheme · material · accent · density · font

Installation

$ pnpm add @vamos-ui/react

The whole kit as one package — get updates by bumping the version. Add the styles to globals.css: @import "@vamos-ui/react/styles.css";

Usage

import { Avatar, AvatarGroup } from "@vamos-ui/react";

<Avatar name="Selin Aydın" src="/people/selin.jpg" status="online" />

<AvatarGroup max={3} aria-label="Assignees">
  {team.map((p) => <Avatar key={p.id} name={p.name} src={p.photo} />)}
</AvatarGroup>

avatarColor(name) returns the same soft background + ink colours for your own components (chart-1…6, mixed with the surface).

In glass mode the ring between stacked avatars uses --avatar-ring (opaque), so the overlap never looks hollow.

Examples

Sizes & shapes

20 / 24 / 32 / 40 / 56 px. xs shows one initial. square is for organisations and workspaces.

Status

The dot is announced with the name ("Zeynep Çelik (In a meeting until 15:30)"). statusLabel overrides the default text.

  • Elif KayaOnline
  • Mert DemirAway · 12 min
  • Zeynep ÇelikIn a meeting until 15:30
  • Can ÖztürkLast seen yesterday

Group

max avatars, then +N ("3 more people"). spacing sets the overlap; total covers lists already cut on the server; onOverflowClick turns +N into a button.

Locale-correct initials

Initials use the provider locale: Turkish uppercases i to İ, so "ilker şahin" becomes İŞ, not IŞ.

en-US
tr-TR

CRM accounts list

Square avatars for companies, a small group for the deal owners.

  • Lumen ArchitectsHannah Okafor · $48,000
    Proposal
  • Bosphorus DentalDr. Kerem Aksoy · $12,600
    Negotiation
  • Northwind TradersLaura Chen · $96,400
    Qualified

API

Avatar

PropTypeDefault
name
Required. Initials, fallback colour and the accessible name.
string—
src
Photo URL. Missing or failing → initials.
string | null—
size
20 / 24 / 32 / 40 / 56 px.
"xs" | "sm" | "md" | "lg" | "xl""md"
shape
square for organisation logos.
"circle" | "square""circle"
status
Presence dot, announced with the name.
"online" | "away" | "busy" | "offline"—
statusLabel
Custom status text ("In a meeting").
string—
fallback
Override the initials (or pass an icon).
ReactNode—
delayMs
Wait before showing the fallback while an image loads.
number300
neutral
Neutral fallback colour instead of the per-name hue.
boolean—
labels
online, away, busy, offline, withStatus, overflow, more.
Partial<AvatarLabels>—

AvatarGroup

PropTypeDefault
max
Avatars shown before +N.
number4
total
Total count when children are already truncated.
number—
size / shape
Applied to every avatar in the group.
Avatar size / shape"md" / "circle"
spacing
Overlap between avatars.
"sm" | "md" | "lg""md"
onOverflowClick
Makes +N a button (open the full list).
() => void—
aria-label
Names the group ("Assignees").
string—

AvatarRoot · AvatarImage · AvatarFallback

PropTypeDefault
size / shape
Same sizes as Avatar.
AvatarRoot—
asChild
Render a framework image (e.g. Next <Image>).
AvatarImage—
delayMs
Delay before the fallback renders.
AvatarFallback—
Previous
Audit log
Next
Backup codes