Zentauri UI
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.

Sample userZU

Zentauri member

Image + fallback pairing

ABC+1

Sizes

SMMDLGXL

Avatar code examples

Use Show output / Show code on each row. Snippets start with a Variant line naming size or animation.

Size: SM

ZU

Size: MD

ZU

Size: LG

ZU

Size: XL

ZU

Appearance: DEFAULT

ZU

Appearance: MUTED

ZU

Appearance: SKY

ZU

Appearance: ROSE

ZU

Appearance: PURPLE

ZU

Appearance: PINK

ZU

Appearance: ORANGE

ZU

Appearance: YELLOW

ZU

Appearance: TEAL

ZU

Appearance: INDIGO

ZU

Appearance: EMERALD

ZU

Appearance: GRAY

ZU

Appearance: AMBER

ZU

Appearance: VIOLET

ZU

Appearance: GRADIENT-BLUE

ZU

Appearance: GRADIENT-GREEN

ZU

Appearance: GRADIENT-RED

ZU

Appearance: GRADIENT-YELLOW

ZU

Appearance: GRADIENT-PURPLE

ZU

Appearance: GRADIENT-TEAL

ZU

Appearance: GRADIENT-INDIGO

ZU

Appearance: GRADIENT-PINK

ZU

Appearance: GRADIENT-ORANGE

ZU

Animation: NONE

ZU

Animation: SUBTLE

ZU
CSS variable overrides

Avatar CSS variables

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

148 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-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);
  /* ...same variables with -dark at the end */
}

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.