Add this component

npx zentauri-ui add avatar

Accessibility notes

Keyboard accessible by default with semantic markup, visible focus treatment, and tokenized states. Add descriptive labels for icon-only or decorative usage.

Dependency notes

Static imports do not pull framer-motion. Use the animated entry only when you want motion and have framer-motion installed.

Display

Avatars for people and teams

Avatars show who is behind an action. Pair AvatarImage with AvatarFallback for resilient loading, and AvatarGroup when several people share a surface.

Zentauri member

Image + fallback pairing

ABC+1

Avatar variants playground

Pick a size, appearance, and animation to preview the avatar live. Toggle Show output / Show code and the snippet updates to match the selected variant.

Size

Appearance

Animation

All appearances

Every shipped appearance token at a glance. Click any swatch to load it into the playground above.

Avatar API

Generated from the package prop types and variant definitions.

Avatar

AvatarProps

Variants

Prop	Type	Default
appearance	`amberaquabluecrimsoncyandefaultelectricemeraldforestgradient-bluegradient-greengradient-indigo`+32	default
size	`lgmdsmxl`	md

Inherited HTML props

Prop	Type	Default
children	`ReactNode`	none
className	`string \| undefined`	none
id	`string \| undefined`	none
onClick	`MouseEventHandler<HTMLSpanElement> \| undefined`	none
style	`CSSProperties \| undefined`	none
title	`string \| undefined`	none

AvatarFallback

AvatarFallbackProps

Behavior

Prop	Type	Default
delayMs	`number \| undefined`	none

Inherited HTML props

Prop	Type	Default
children	`ReactNode`	none
className	`string \| undefined`	none
id	`string \| undefined`	none
onClick	`MouseEventHandler<HTMLSpanElement> \| undefined`	none
style	`CSSProperties \| undefined`	none
title	`string \| undefined`	none

AvatarGroup

AvatarGroupProps

Behavior

Prop	Type	Default
maxMax avatars before +N overflow label	`number \| undefined`	none

Inherited HTML props

Prop	Type	Default
children	`ReactNode`	none
className	`string \| undefined`	none
id	`string \| undefined`	none
onClick	`MouseEventHandler<HTMLDivElement> \| undefined`	none
style	`CSSProperties \| undefined`	none
title	`string \| undefined`	none

AvatarImage

AvatarImageProps

Inherited HTML props

Prop	Type	Default
children	`ReactNode`	none
className	`string \| undefined`	none
id	`string \| undefined`	none
onClick	`MouseEventHandler<HTMLImageElement> \| undefined`	none
style	`CSSProperties \| undefined`	none
title	`string \| undefined`	none

AvatarAnimated

AvatarAnimatedProps

animated

Behavior

Prop	Type	Default
animation	`AvatarAnimation \| undefined`	none
appearance	'default' \| 'blue' \| 'cyan' \| 'green' \| 'lime' \| 'mint' \| 'ocean' \| 'sapphire' \| 'lavender' \| 'ruby' \| 'red' \| 'slate' \| 'zinc' \| 'stone' \| 'royal' \| 'electric' \| 'forest' \| 'sunset' \| 'magenta' \| 'crimson' \| 'aqua' \| 'plum' \| 'sky' \| 'rose' \| 'purple' \| 'pink' \| 'orange' \| 'yellow' \| 'teal' \| 'indigo' \| 'emerald' \| 'gradient-blue' \| 'gradient-green' \| 'gradient-red' \| 'gradient-yellow' \| 'gradient-purple' \| 'gradient-teal' \| 'gradient-indigo' \| 'gradient-pink' \| 'gradient-orange' \| 'gray' \| 'violet' \| 'muted' \| 'amber' \| null \| undefined	none
size	`'md' \| 'sm' \| 'lg' \| 'xl' \| null \| undefined`	none

Inherited HTML props

Prop	Type	Default
children	`ReactNode`	none
className	`string \| undefined`	none
id	`string \| undefined`	none
onClick	`MouseEventHandler<HTMLSpanElement> \| undefined`	none
style	`CSSProperties \| undefined`	none
title	`string \| undefined`	none

CSS variable overrides

Avatar CSS variables

Override these avatar variables on :root, a theme selector, or a component wrapper.

274 variables

Pattern: --zui-<component>-<slot?>-<variant?>-<property>-<state?>-dark?

:root {
  --zui-avatar-border: #0000001a;
  --zui-avatar-fg: oklch(37.2% 0.044 257.287);
  --zui-avatar-default-border: #0000001a;
  --zui-avatar-default-bg: #0000001a;
  --zui-avatar-default-fg: oklch(37.2% 0.044 257.287);
  --zui-avatar-muted-border: #00000066;
  --zui-avatar-muted-bg: oklch(98.4% 0.003 247.858);
  --zui-avatar-muted-fg: oklch(37.2% 0.044 257.287);
  --zui-avatar-blue-border: #2563eb;
  --zui-avatar-blue-bg: #2563eb1a;
  --zui-avatar-blue-fg: #0f172a;
  --zui-avatar-cyan-border: #0891b2;
  --zui-avatar-cyan-bg: #0891b21a;
  --zui-avatar-cyan-fg: #0f172a;
  --zui-avatar-green-border: #16a34a;
  --zui-avatar-green-bg: #16a34a1a;
  --zui-avatar-green-fg: #0f172a;
  --zui-avatar-lime-border: #65a30d;
  --zui-avatar-lime-bg: #65a30d1a;
  --zui-avatar-lime-fg: #0f172a;
  --zui-avatar-mint-border: #10b981;
  --zui-avatar-mint-bg: #10b9811a;
  --zui-avatar-mint-fg: #0f172a;
  --zui-avatar-ocean-border: #0284c7;
  --zui-avatar-ocean-bg: #0284c71a;
  --zui-avatar-ocean-fg: #0f172a;
  --zui-avatar-sapphire-border: #1d4ed8;
  --zui-avatar-sapphire-bg: #1d4ed81a;
  --zui-avatar-sapphire-fg: #0f172a;
  --zui-avatar-lavender-border: #8b5cf6;
  --zui-avatar-lavender-bg: #8b5cf61a;
  --zui-avatar-lavender-fg: #0f172a;
  --zui-avatar-ruby-border: #be123c;
  --zui-avatar-ruby-bg: #be123c1a;
  --zui-avatar-ruby-fg: #0f172a;
  --zui-avatar-red-border: #dc2626;
  --zui-avatar-red-bg: #dc26261a;
  --zui-avatar-red-fg: #0f172a;
  --zui-avatar-slate-border: #475569;
  --zui-avatar-slate-bg: #4755691a;
  --zui-avatar-slate-fg: #0f172a;
  --zui-avatar-zinc-border: #52525b;
  --zui-avatar-zinc-bg: #52525b1a;
  --zui-avatar-zinc-fg: #0f172a;
  --zui-avatar-stone-border: #57534e;
  --zui-avatar-stone-bg: #57534e1a;
  --zui-avatar-stone-fg: #0f172a;
  --zui-avatar-royal-border: #4338ca;
  --zui-avatar-royal-bg: #4338ca1a;
  --zui-avatar-royal-fg: #0f172a;
  --zui-avatar-electric-border: #0ea5e9;
  --zui-avatar-electric-bg: #0ea5e91a;
  --zui-avatar-electric-fg: #0f172a;
  --zui-avatar-forest-border: #166534;
  --zui-avatar-forest-bg: #1665341a;
  --zui-avatar-forest-fg: #0f172a;
  --zui-avatar-sunset-border: #ea580c;
  --zui-avatar-sunset-bg: #ea580c1a;
  --zui-avatar-sunset-fg: #0f172a;
  --zui-avatar-magenta-border: #c026d3;
  --zui-avatar-magenta-bg: #c026d31a;
  --zui-avatar-magenta-fg: #0f172a;
  --zui-avatar-crimson-border: #b91c1c;
  --zui-avatar-crimson-bg: #b91c1c1a;
  --zui-avatar-crimson-fg: #0f172a;
  --zui-avatar-aqua-border: #0f766e;
  --zui-avatar-aqua-bg: #0f766e1a;
  --zui-avatar-aqua-fg: #0f172a;
  --zui-avatar-plum-border: #7e22ce;
  --zui-avatar-plum-bg: #7e22ce1a;
  --zui-avatar-plum-fg: #0f172a;
  --zui-avatar-sky-border: oklch(44.3% 0.11 240.79);
  --zui-avatar-sky-bg: oklch(95.1% 0.026 236.824 / 0.5);
  --zui-avatar-sky-fg: oklch(37.2% 0.044 257.287);
  --zui-avatar-rose-border: oklch(45.5% 0.188 13.697);
  --zui-avatar-rose-bg: oklch(94.1% 0.03 12.58 / 0.5);
  --zui-avatar-rose-fg: oklch(37.2% 0.044 257.287);
  --zui-avatar-purple-border: oklch(43.8% 0.218 303.724);
  --zui-avatar-purple-bg: oklch(94.6% 0.033 307.174 / 0.5);
  --zui-avatar-purple-fg: oklch(37.2% 0.044 257.287);
  --zui-avatar-pink-border: oklch(45.9% 0.187 3.815);
  --zui-avatar-pink-bg: oklch(94.8% 0.028 342.258 / 0.5);
  --zui-avatar-pink-fg: oklch(37.2% 0.044 257.287);
  --zui-avatar-orange-border: oklch(47% 0.157 37.304);
  --zui-avatar-orange-bg: oklch(95.4% 0.038 75.164 / 0.5);
  --zui-avatar-orange-fg: oklch(37.2% 0.044 257.287);
  --zui-avatar-yellow-border: oklch(47.6% 0.114 61.907);
  --zui-avatar-yellow-bg: oklch(97.3% 0.071 103.193 / 0.5);
  --zui-avatar-yellow-fg: oklch(37.2% 0.044 257.287);
  --zui-avatar-teal-border: oklch(43.7% 0.078 188.216);
  --zui-avatar-teal-bg: oklch(95.3% 0.051 180.801 / 0.5);
  --zui-avatar-teal-fg: oklch(37.2% 0.044 257.287);
  --zui-avatar-indigo-border: oklch(39.8% 0.195 277.366);
  --zui-avatar-indigo-bg: oklch(93% 0.034 272.788 / 0.5);
  --zui-avatar-indigo-fg: oklch(37.2% 0.044 257.287);
  --zui-avatar-emerald-border: oklch(43.2% 0.095 166.913);
  --zui-avatar-emerald-bg: oklch(95% 0.052 163.051 / 0.5);
  --zui-avatar-emerald-fg: oklch(37.2% 0.044 257.287);
  --zui-avatar-gray-border: oklch(27.8% 0.033 256.848);
  --zui-avatar-gray-bg: oklch(96.7% 0.003 264.542 / 0.5);
  --zui-avatar-gray-fg: oklch(37.2% 0.044 257.287);
  --zui-avatar-amber-border: oklch(47.3% 0.137 46.201);
  --zui-avatar-amber-bg: oklch(96.2% 0.059 95.617 / 0.5);
  --zui-avatar-amber-fg: oklch(37.2% 0.044 257.287);
  --zui-avatar-violet-border: oklch(43.2% 0.232 292.759);
  --zui-avatar-violet-bg: oklch(94.3% 0.029 294.588 / 0.5);
  --zui-avatar-violet-fg: oklch(37.2% 0.044 257.287);
  --zui-avatar-gradient-blue-from: oklch(62.3% 0.214 259.815);
  --zui-avatar-gradient-blue-to: oklch(62.7% 0.265 303.9);
  --zui-avatar-gradient-blue-fg: oklch(37.2% 0.044 257.287);
  --zui-avatar-gradient-green-from: oklch(72.3% 0.219 149.579);
  --zui-avatar-gradient-green-to: oklch(76.8% 0.233 130.85);
  --zui-avatar-gradient-green-fg: oklch(37.2% 0.044 257.287);
  --zui-avatar-gradient-red-from: oklch(63.7% 0.237 25.331);
  --zui-avatar-gradient-red-to: oklch(65.6% 0.241 354.308);
  --zui-avatar-gradient-red-fg: oklch(37.2% 0.044 257.287);
  --zui-avatar-gradient-yellow-from: oklch(79.5% 0.184 86.047);
  --zui-avatar-gradient-yellow-to: oklch(70.5% 0.213 47.604);
  --zui-avatar-gradient-yellow-fg: oklch(37.2% 0.044 257.287);
  --zui-avatar-gradient-purple-from: oklch(62.7% 0.265 303.9);
  --zui-avatar-gradient-purple-to: oklch(65.6% 0.241 354.308);
  --zui-avatar-gradient-purple-fg: oklch(37.2% 0.044 257.287);
  --zui-avatar-gradient-teal-from: oklch(70.4% 0.14 182.503);
  --zui-avatar-gradient-teal-to: oklch(71.5% 0.143 215.221);
  --zui-avatar-gradient-teal-fg: oklch(37.2% 0.044 257.287);
  --zui-avatar-gradient-indigo-from: oklch(58.5% 0.233 277.117);
  --zui-avatar-gradient-indigo-to: oklch(62.7% 0.265 303.9);
  --zui-avatar-gradient-indigo-fg: oklch(37.2% 0.044 257.287);
  --zui-avatar-gradient-pink-from: oklch(65.6% 0.241 354.308);
  --zui-avatar-gradient-pink-to: oklch(64.5% 0.246 16.439);
  --zui-avatar-gradient-pink-fg: oklch(37.2% 0.044 257.287);
  --zui-avatar-gradient-orange-from: oklch(70.5% 0.213 47.604);
  --zui-avatar-gradient-orange-to: oklch(63.7% 0.237 25.331);
  --zui-avatar-gradient-orange-fg: oklch(37.2% 0.044 257.287);
  --zui-avatar-fallback-bg: oklch(92.9% 0.013 255.508);
  --zui-avatar-fallback-fg: oklch(27.9% 0.041 260.031);
  --zui-avatar-group-ring: #ffffff;
}

/* Dark theme variables follow the same names with -dark appended. */
.dark {
  --zui-avatar-border-dark: #ffffff1a;
  --zui-avatar-fg-dark: oklch(92.9% 0.013 255.508);
}

Overview

Sizes map to common touch targets. Motion presets are intentionally subtle so they stay appropriate inside dense UI.

Common use cases

Headers and account menus.
Comment threads and activity feeds.
Table rows for assignees.
Stacked collaborators on documents.

FAQ

What happens when an image fails to load?

AvatarFallback renders when the image errors or while the image is still loading, with an optional delay to reduce flicker for fast caches.

How does AvatarGroup max work?

Pass max to cap visible avatars; additional participants surface as a +N overflow chip with an aria-label describing how many remain.