Avatar

A userpic container. Avatar shows one of three things, in priority order: a supplied image, a seed-generated placeholder figure, or initials. The generated figure imitates a framed portrait — a head and shoulders over a colored background — with no face or gender indicators, so an app can fill an empty slot with a distinct, on-brand picture per user without an uploaded photo.

An alphanumeric seed drives the result deterministically: the same seed always renders the same avatar, and different seeds are distinguishable. A generator config caps each dimension to your brand.

Generated userpic

Pass a seed (a stable user id) and a name. With no generator, each seed draws a varied figure: background, head, and body colors, the figure’s scale, the head and shoulder angles, and the corner radius of each shape all move with the seed, while the head and body hues stay coordinated with the background.

<Avatar seed="user-42" name="Vlad Korobov" />
<Avatar seed="lena-r" name="Lena Rossi" />
<Avatar seed="8f21ac" name="Sam Okafor" />

Initials

Turn the shape dimensions off in the generator and the avatar falls back to initials — the first letter of each of the first three words of name — over the generated background. The background color still varies with the seed.

const initials = {
  headRadiusTop: { mode: 'off' },
  headRadiusBottom: { mode: 'off' },
  bodyBorderRadius: { mode: 'off' },
}

<Avatar name="Vlad Korobov" generator={initials} />
<Avatar name="Marie Skłodowska Curie" generator={initials} />
<Avatar name="Madonna" generator={initials} />

Image and badge

Set src to show an uploaded photo instead of a generated figure, cropped to fill the container.

badge adds a corner badge, colored by tone, on any avatar — image or generated. It takes any named tone, so the application decides what each one means: success for online, critical for busy, warning for idle, neutral for offline. Named tones track light and dark mode automatically.

The badge sits in a hole masked out of the picture rather than behind a painted ring, so whatever is behind the avatar shows through the gap and no ring color has to track the surface.

<Avatar round src="/anta-logo.svg" name="Anta" badge="success" />
<Avatar seed="lena-r" name="Lena Rossi" badge="critical" />
<Avatar seed="8f21ac" name="Sam Okafor" badge="warning" />
<Avatar seed="k-tanaka" name="Kenji Tanaka" badge="info" />

badge also accepts any literal CSS color for a one-off badge, derived in oklch the same way a named tone is.

<Avatar seed="a-lee" name="Ann Lee" badge="#ff1493" />
<Avatar seed="b-qi" name="Bo Qi" badge="rebeccapurple" />

Size

size is small (32px), medium (44px, the default), or large (64px). Pass a number for a pixel size.

<Avatar seed="user-42" name="Vlad Korobov" size="small" />
<Avatar seed="user-42" name="Vlad Korobov" size="large" />
<Avatar seed="user-42" name="Vlad Korobov" size={96} />

Round

round makes the frame a circle. Pass a number (px) or a CSS length for a custom radius instead. The badge hugs the circle’s edge on a round frame.

<Avatar round seed="user-42" name="Vlad Korobov" />
<Avatar round seed="lena-r" name="Lena Rossi" badge="success" />
<Avatar seed="k-tanaka" name="Kenji Tanaka" round={10} />

Brand constraints

The generator config caps the space so every avatar sits on your brand. Each dimension takes one of four modes: off (excluded, a fixed default), any (its full natural range), range (an explicit range), or list (a set of values the seed picks from). Edit the config in the playground’s Code tab to try them.

const brand = {
  bgColor: { mode: 'range', l: [0.5, 0.62], c: [0.09, 0.15], h: [255, 285] },
  harmony: true,
}

<Avatar seed={user.id} name={user.name} generator={brand} />

const palette = {
  bgColor: { mode: 'list', values: ['#6c5ce7', '#00b894', '#e17055', '#0984e3', '#fdcb6e'] },
  headRadiusTop: { mode: 'off' },
  headRadiusBottom: { mode: 'off' },
  bodyBorderRadius: { mode: 'off' },
}

<Avatar name={user.name} generator={palette} />

The dimensions

Corner radius is normalized: 0 is a square corner and 1 is fully round, so a head with both radii at 1 is a circle. Above 1 the head elongates into an oval, spending the excess on that half’s height — 1.3 on both radii is a tall oval, and more at the bottom than the top is an egg.

Two rules keep the head reading as a head. The bottom is never rounded less than the top, so a value below the top radius is raised to match it: a rounder crown over a squarer jaw reads mechanical, and the reverse reads natural. And under any both radii average near or above 1, so heads read round to oval unless you narrow them yourself.

interface AvatarGenConfig {
  bgColor?: ColorDim
  headColor?: ColorDim
  bodyColor?: ColorDim
  figureScale?: ScalarDim
  figureTranslate?: Vec2Dim
  figureAngle?: ScalarDim
  headAngle?: ScalarDim
  bodyAngle?: ScalarDim
  figureGap?: ScalarDim
  headRadiusTop?: ScalarDim
  headRadiusBottom?: ScalarDim
  bodyBorderRadius?: ScalarDim
  harmony?: boolean
}

type DimMode = 'off' | 'any' | 'range' | 'list'

interface ScalarDim {
  mode?: DimMode
  min?: number      // range: lower bound
  max?: number      // range: upper bound
  values?: number[] // list: the allowed values
}

interface ColorDim {
  mode?: DimMode
  l?: [number, number] // range: lightness, 0 to 1
  c?: [number, number] // range: chroma, 0 to ~0.4
  h?: [number, number] // range: hue, 0 to 360
  values?: string[]    // list: the allowed CSS colors
}

interface Vec2Dim {
  mode?: DimMode              // 'list' is not used here
  x?: [number, number]        // range: horizontal bounds
  y?: [number, number]        // range: vertical bounds
  values?: [number, number][] // list: allowed [x, y] points
}

<a-avatar seed="user-42" name="Vlad Korobov"></a-avatar>

<a-avatar
  name="Vlad Korobov"
  config='{"headRadiusTop":{"mode":"off"},"headRadiusBottom":{"mode":"off"},"bodyBorderRadius":{"mode":"off"}}'
></a-avatar>

a-avatar.badge-dot {
  --avatar-badge-ratio: 0.34;  /* a larger badge */
  --avatar-badge-gap: 4px;     /* in a wider cutout */
}