# Avatar (/docs/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. ```tsx import { Avatar } from '@42-central/ui-react/avatar'; ``` ## Playground [#playground] ### Full prop browser [#full-prop-browser] ## Fallback content [#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
## Colors [#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.
{COLORS.map((c) => ( ))}
## Auto-color from name or initials [#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.
`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). ```tsx import { Avatar, AVATAR_PALETTE } from '@42-central/ui-react/avatar'; ``` ## Sizes & radius [#sizes--radius] `size` is the kit's shared `xs`–`xl` scale. `radius` defaults to `full` — unlike [`ThemeIcon`](/docs/theme-icon), which defaults to `md` — because an avatar reads as circular by default.
## Avatar.Group [#avatargroup] `Avatar.Group` overlaps a row (or, with `orientation="vertical"`, a column) of standalone `Avatar`s, 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. 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. 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: `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: ## API [#api] ### Avatar [#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`](/docs/skeleton) documents for its own opt-out). ### Avatar.Group [#avatargroup-1] `Avatar.Group` forwards remaining props (incl. `asChild`) to its root `div`. ## Accessibility [#accessibility] Pass `alt` describing the person or entity whenever `src` is set — it's forwarded straight to the underlying ``. 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.