Avatar

User profile images with fallback initials and status indicators.

Shape

Status Position

Pulse

Ring

Random Color

Interactive

Size

Intent

Status

Ring Intent

Name

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

01 Examples

An Avatar shows the src photo, or the initials from name (the first letter of each word, up to two) when there is none. randomColor gives each name a stable colour, and children replace the initials with your own content.

Identity colours

randomColor hashes each name to a fixed hue from the identity palette, so people without a photo stay distinct and one person keeps the same colour everywhere.

<Avatar name="Ada Lovelace" randomColor size="lg" />
<Avatar name="Alan Turing" randomColor size="lg" />
<Avatar name="Grace Hopper" randomColor size="lg" />
<Avatar name="Katherine Johnson" randomColor size="lg" />
<Avatar name="Barbara Liskov" randomColor size="lg" />
<Avatar name="Edsger Dijkstra" randomColor size="lg" />

Photo, with initials as the fallback

src renders the photo. If it is missing or fails to load, the avatar falls back to the initials from name inside the same fixed box, so the layout never shifts.

<Avatar src="https://i.pravatar.cc/96?img=12" name="Marcus Chen" size="lg" />
<Avatar src="https://i.pravatar.cc/96?img=5" name="Sarah Okoro" size="lg" />
<Avatar src="data:image/jpeg,broken" name="Priya Nair" size="lg" />

Custom content

children replace the 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>

For overlapping stacks with an overflow count, see AvatarGroup.

02 Status

status adds a presence dot in the corner set by statusPosition. Each value carries its own colour, and pulse adds a radar ring in the same hue that draws the eye to a presence change.

`status`	Example
`online`	AL
`away`	AT
`busy`	GH
`offline`	KJ

03 Customization

Gradient identities

Paint the disc with slotClasses.frame: it keeps the avatar's circular shape, size and centering, and only the gradient fill and initials colour are raw. The intent palette carries no per-identity gradient.

<Avatar
  size="lg"
  slotClasses={{ frame: 'bg-linear-to-br from-violet-500 to-fuchsia-500 text-white' }}
>
  FD
</Avatar>
<Avatar
  size="lg"
  slotClasses={{ frame: 'bg-linear-to-br from-cyan-500 to-blue-500 text-white' }}
>
  AK
</Avatar>
<Avatar
  size="lg"
  slotClasses={{ frame: 'bg-linear-to-br from-amber-400 to-orange-500 text-neutral-900' }}
>
  ST
</Avatar>

This is one of five ways to restyle a block. See Customization for class, slotClasses, unstyled, preset and provider-level overrides.

04 Accessibility

ARIA

An interactive avatar (clickable, interactive, or onclick) carries role="button" and an aria-label taken from alt or name. A static avatar exposes its name through the image's alt, or renders initials. The presence dot is announced separately, as an image labelled “Status: online”. Hide a purely decorative avatar with aria-hidden.

Keyboard

Interactive avatars are focusable with Tab and activate on Enter / Space. A static avatar is skipped in the tab order.

Image fallback

When the image is missing or fails to load, the avatar falls back to children if given, otherwise to the initials from name, so it is never empty.

Motion and contrast

The pulse ring stops animating under prefers-reduced-motion. Under prefers-contrast: more the disc gains a delineating outline.

05 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 background.
`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')

06 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.

07 Installation

Import

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

llm.txt