Avatar

User profile images with fallback initials, status indicators, and configurable shapes.

Shape

Status Position

Pulse

Ring

Random Color

Interactive

Size

Intent

Status

Ring Intent

Name

<Avatar
  name="Jane Doe"
  size="lg"
  status=""
/>

01 Examples

Team Row

Overlapping avatars with a children-based overflow counter — the standard way to show a member list in a row that has no room for one.

<div class="flex -space-x-3">
  <Avatar name="Anna" size="lg" randomColor ring ringIntent="neutral" />
  <Avatar name="Ben" size="lg" randomColor ring ringIntent="neutral" />
  <Avatar name="Cleo" size="lg" randomColor ring ringIntent="neutral" />
  <Avatar name="Dan" size="lg" randomColor ring ringIntent="neutral" />
  <Avatar
    unstyled
    class="bg-surface-elevated text-text-secondary ring-surface-base flex h-12 w-12 items-center justify-center rounded-full text-xs font-semibold ring-2"
  >
    +5
  </Avatar>
</div>

Custom Children

Use children to render arbitrary content instead of auto-generated initials — an icon for a system account, a count for a group, a glyph for a placeholder.

<Avatar size="xl" intent="primary">
  <UserIcon size={24} />
</Avatar>
<Avatar size="xl" intent="success">
  <span class="text-lg">42</span>
</Avatar>
<Avatar size="xl" intent="warning" variant="rounded">
  <span class="text-base">!</span>
</Avatar>

Mint micro-interactions

Mints only apply when the avatar is interactive (clickable, interactive, or onclick). Recommended: scale and glow — they read as 'this profile is tappable' without being playful. Avoid bounce, rotate, and wiggle on profile pictures — they undermine the calm a face conveys.

<Avatar name="Scale" clickable mint="scale" size="lg" />
<Avatar name="Glow" clickable mint="glow" intent="primary" size="lg" />
<Avatar name="Static" clickable size="lg" />

02 Customization

Gradient Avatar

Use unstyled with children for fully custom styling.

<Avatar
  unstyled
  class="flex h-14 w-14 items-center justify-center rounded-full bg-linear-to-br from-violet-500 to-fuchsia-500 text-lg font-bold text-white shadow-lg shadow-violet-500/25"
>
  FD
</Avatar>
<Avatar
  unstyled
  class="flex h-14 w-14 items-center justify-center rounded-full bg-linear-to-br from-cyan-500 to-blue-500 text-lg font-bold text-white shadow-lg shadow-cyan-500/25"
>
  AK
</Avatar>
<Avatar
  unstyled
  class="flex h-14 w-14 items-center justify-center rounded-2xl bg-linear-to-br from-amber-400 to-orange-500 text-lg font-bold text-neutral-900 shadow-lg shadow-amber-500/25"
>
  ST
</Avatar>

Beyond unstyled + class, Avatar exposes base, frame, image, fallback, and status through slotClasses. A recurring identity treatment — like the gradient tiles above — is best registered as a BlocksProvider preset (presets.Avatar) and applied via preset; see Customization.

03 Accessibility

ARIA

The aria-label is derived from alt or name. Interactive avatars receive role="button". Purely decorative avatars can be hidden via aria-hidden.

Keyboard

Interactive avatars are focusable via Tab and activate with Enter / Space. Non-interactive avatars are skipped in the tab order.

Image Fallback

When the image fails to load, the component falls back to children (if provided) or initials generated from name, ensuring content is always visible.

04 API Reference

25 props

Prop	Type	Default	Description
`alt`	`string`	—	Alt text for the image. Defaults to `name`.
`children`	`Snippet`	—	Custom fallback content rendered instead of auto-generated initials. Useful for overflow counters, icons, or fully custom avatars with `unstyled`.
`class`	`string`	—	Extra classes merged onto the root element.
`clickable`	`boolean`	—	Mark the avatar as clickable (adds hover/focus styles and keyboard support). Alias for the `interactive` variant.
`intent` variant	dangerneutralprimarysecondary +2 more	`neutral`	Controls the color theme and semantic meaning of the Avatar. Affects the overall appearance and user perception. Available options: danger, neutral, primary, and 3 more.
`interactive` variant	true	`false`	Controls the interactive behavior and appearance of the Avatar component. Available options: true.
`mint`	`MintProp`	`'none'`	Micro-interaction preset applied to the avatar. Only applies while interactive (`clickable`, `interactive`, or `onclick`).
`name`	`string`	—	Full user name — used for initials generation, `randomColor` hashing, and `aria-label`.
`onclick`	`(event: MouseEvent) => void`	—	Click handler. Automatically enables interactive styles.
`onHover`	`(hovered: boolean) => void`	—	Called when the hover state changes.
`preset`	`string`	—	Apply a named preset registered via `<BlocksProvider presets={{ Avatar: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project.
`pulse` variant	true	`false`	Controls the pulse behavior and appearance of the Avatar component. Available options: true.
`randomColor`	`boolean`	—	Derive a deterministic background color from `name`. The same name always produces the same color, making it easy to visually distinguish users without images. Overrides `intent`. Picks from the 12-slot identity palette (`--color-avatar-1` … `--color-avatar-12`), which resolves light/dark automatically — override those tokens to rebrand it. Without a `name` there is no identity to encode, so the avatar keeps its neutral surface.
`ring` variant	true	`false`	Controls the ring behavior and appearance of the Avatar component. Available options: true.
`ringColor`	`string`	—	Custom ring color (CSS value). Overrides `ringIntent` when set.
`ringIntent` variant	dangerneutralprimarysecondary +2 more	`primary`	Controls the ringIntent behavior and appearance of the Avatar component. Available options: danger, neutral, primary, and 3 more.
`size` variant	2xllgmdsm +2 more	`md`	Controls the dimensions, padding, and text size of the Avatar. Affects the component's physical footprint. Available options: 2xl, lg, md, and 3 more.
`slotClasses`	`Partial<Record<AvatarSlots, string>>`	—	Per-slot class overrides merged with tv styles. Slots: base \| frame \| image \| fallback \| status
`src`	`string`	—	Image URL. Falls back to initials or `children` when empty or on load error.
`status` variant	awaybusyofflineonline	—	Controls the status behavior and appearance of the Avatar component. Available options: away, busy, offline, online.
`statusPosition` variant	bottom-leftbottom-righttop-lefttop-right	`bottom-right`	Controls the statusPosition behavior and appearance of the Avatar component. Available options: bottom-left, bottom-right, top-left, top-right.
`unstyled`	`boolean`	—	Remove all default tv classes.
`variant` variant	circleroundedsquare	`circle`	Controls the visual style and presentation of the Avatar. Determines the component's visual treatment. Available options: circle, rounded, square.
`...AvatarVariants` variant	`VariantProps`	—	Styling variants from AvatarVariants
`...HTMLAttributes<HTMLDivElement>` inherited	`HTMLAttributes`	—	HTML attributes (excluding: 'children')

05 Types

Local type definitions used by this component.

7 types

Only referenced

Name	Kind	Category	Used by	Description
AvatarProps	interface	props	0	—
AvatarVariants	type	variant	1	—
AvatarSlots	type	variant	0	Slot names derived from the tv() config — single source of truth for slotClasses.
MintProp	type	helper	1	—
MintName	type	helper	0	A mint name: a built-in (autocompleted), `'none'` to disable, or any consumer-registered name. `(string & {})` keeps the registry open — a custom name still type-checks, it just isn't suggested. A typo therefore also still compiles (it resolves like an unregistered custom name and warns at runtime); the union buys completion and docs, not validation.
MintConfig	interface	helper	0	—
BuiltinMintName	type	helper	0	Built-in mint names as a literal union, so the `mint` prop autocompletes across every component — the single list the hand-curated playground knobs and docs used to drift away from.

06 Installation

Import

import { Avatar } from '@urbicon-ui/blocks';

llm.txt