Avatar

Avatar wraps Ark UI's Avatar machine, which already tracks image-load state (loading → loaded/error): pass src and it renders the image once it loads, and falls back automatically — to children, to initials derived from name, or to a generic person icon — when there's no image or it fails to load. color="name" / color="initials" can derive a stable accent per person automatically, with no color picked by hand.

import { Avatar } from '@42-central/ui-react/avatar';

<Avatar src={user.avatarUrl} name={user.fullName} color="pink" />
<Avatar name="Ada Lovelace" color="teal" />
<Avatar />

Playground

<Component
  color="pink"
  size="md"
  name="Ada Lovelace"
  src="https://i.pravatar.cc/150?img=12"
/>

Full prop browser

Fallback content

Explicit children always wins, then name-derived content, then a placeholder icon. This resolves the same way regardless of whether src is missing entirely or present but failed to load. display ("initials" by default, or "name") controls which name-derived form is shown — "name" is a single leading letter, since the full name would overflow a small circle.

AL

AL

A

AL

// Code

<Avatar src="https://i.pravatar.cc/150?img=12" name="Ada Lovelace" color="pink" />
<Avatar name="Ada Lovelace" color="pink" />
<Avatar name="Ada Lovelace" display="name" color="pink" />
<Avatar color="pink">AL</Avatar>
<Avatar />

Colors

No variant axis — Avatar is always the same soft-surface look (the same treatment Pill and Badge's light variant use), neutral gray by default. Pass color to tint the surface and text with any palette accent.

<Avatar name="Ada Lovelace" />
<Avatar color="brand" name="Ada Lovelace" />
<Avatar color="green" name="Grace Hopper" />
<Avatar color="purple" name="Zendaya" />

Auto-color from name or initials

Set color="initials" or color="name" to skip picking a color by hand — it's deterministically hashed instead, so the same input always resolves to the same accent.

• "initials" hashes the derived initials: two different people who happen to share initials get the same color, useful for visual grouping.
• "name" hashes the full name directly: the same two people almost always get different colors, useful for per-person distinction even when initials collide.

{/* "Ada Lovelace" and "Alex Lambert" both have the initials "AL" */}
<Avatar color="initials" name="Ada Lovelace" />
<Avatar color="initials" name="Alex Lambert" />
{/* same two names, but color="name" tells them apart */}
<Avatar color="name" name="Ada Lovelace" />
<Avatar color="name" name="Alex Lambert" />

palette restricts (or extends) which colors the hash can land on — it defaults to AVATAR_PALETTE, a curated 9-color set that excludes brand (the kit's own primary/CTA identity color) and neutral (too muted to read as a distinct accent).

import { Avatar, AVATAR_PALETTE } from '@42-central/ui-react/avatar';

<Avatar color="name" name="Ada Lovelace" palette={['blue', 'purple']} />
<Avatar color="name" name="Ada Lovelace" palette={[...AVATAR_PALETTE, 'brand']} />

Sizes & radius

size is the kit's shared xs–xl scale. radius defaults to full — unlike ThemeIcon, which defaults to md — because an avatar reads as circular by default.

<Avatar size="xs" name="Ada Lovelace" />
<Avatar size="sm" name="Ada Lovelace" />
<Avatar size="md" name="Ada Lovelace" />
<Avatar size="lg" name="Ada Lovelace" />
<Avatar size="xl" name="Ada Lovelace" />

<Avatar radius="xs" color="pink" name="Ada Lovelace" />
<Avatar radius="md" color="pink" name="Ada Lovelace" />
<Avatar radius="xl" color="pink" name="Ada Lovelace" />
<Avatar radius="full" color="pink" name="Ada Lovelace" />

Avatar.Group

Avatar.Group overlaps a row (or, with orientation="vertical", a column) of standalone Avatars, the classic stacked-avatars look — each one gets a transparent notch cut into it (via mask-image) exactly where its successor overlaps it, so the separation is true see-through space rather than a painted border, and it reads correctly over any page background. It's pure layout — it doesn't resize or restyle its children, so set size/color per Avatar. spacing (the shared size scale) controls how much they overlap.

AL

GH

ZE

+4

// Code

<Avatar.Group>
  <Avatar src="https://i.pravatar.cc/150?img=12" name="Ada Lovelace" />
  <Avatar name="Grace Hopper" color="teal" />
  <Avatar name="Zendaya" color="purple" />
  <Avatar color="neutral">+4</Avatar>
</Avatar.Group>

There's no built-in overflow counter — compose one yourself as a trailing Avatar (as above), the same way Mantine's own docs demonstrate it.

<Avatar.Group spacing="xs">...</Avatar.Group>
<Avatar.Group spacing="xl">...</Avatar.Group>

The notch matches each avatar's own radius, not just the default circle — a rounded-square avatar gets a true rounded-rect cutout that follows its neighbor's actual silhouette, not a circular bite:

AL

GH

ZE

+4

// Code

<Avatar.Group>
  <Avatar radius="md" src="https://i.pravatar.cc/150?img=12" name="Ada Lovelace" />
  <Avatar radius="md" name="Grace Hopper" color="teal" />
  <Avatar radius="md" name="Zendaya" color="purple" />
  <Avatar radius="md" color="neutral">+4</Avatar>
</Avatar.Group>

orientation="vertical" stacks them as a column instead, each one overlapping the one above it and the notch cut at the bottom edge. A column runs top-to-bottom in either text direction, so dir doesn't affect it:

AL

GH

ZE

+4

AL

GH

ZE

+4

// Code

<Avatar.Group orientation="vertical">
  <Avatar src="https://i.pravatar.cc/150?img=12" name="Ada Lovelace" />
  <Avatar name="Grace Hopper" color="teal" />
  <Avatar name="Zendaya" color="purple" />
  <Avatar color="neutral">+4</Avatar>
</Avatar.Group>

API

Avatar

No asChild — children is already repurposed as fallback content, which conflicts with Ark's "single child to render as" requirement for polymorphism (the same reasoning Skeleton documents for its own opt-out).

Avatar.Group

Avatar.Group forwards remaining props (incl. asChild) to its root div.

Accessibility

Pass alt describing the person or entity whenever src is set — it's forwarded straight to the underlying <img>. A text-only Avatar (initials or icon fallback) renders as plain content with no implicit role; wrap it with your own aria-label if it needs to announce more than its visible text.

Changelog