Avatar

<Avatar src="/u/alice.jpg" alt="Alice Liddell" fallback="AL" />
<Avatar fallback="?" size="lg" />
<Avatar shape="square" fallback="ML" />

Install: @helixui/core

import { Avatar } from '@helixui/core'

status: stable · since: 0.1.0

Tags: user, identity, image, fallback, circle

Live playground

Open the full editor or source on GitHub.

Anatomy

●  ← circular image; if missing → initials on tinted bg

Layout

display — inline-block
width — content
height — content
intrinsicSize — 24/32/40/48/64px square (xs/sm/md/lg/xl)
stackable — true
fullBleed — false

Visual

A circular image with rounded fallback when the image fails to load. Fallback shows uppercase initials on a deterministic tinted background derived from the name. Optional ring (border) or PresenceDot can sit on top.

Props

Name	Type	Default	Description
`src`	`string`	—	Image URL.
`alt`	`string`	—	Accessible label. Used as `aria-label`. If empty, `fallback` is used.
`fallback`	`string`	—	Text to display when no image is available — typically initials.
`size`	`'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'`	`md`	Avatar size.
`shape`	`'circle' \| 'square'`	`circle`	Avatar shape.

Tokens used

color.bg.action.neutral.default, color.text.secondary, font.family.sans, font.weight.semibold, font.size.xs, font.size.sm, font.size.md, font.size.xl, radius.full, radius.md

Accessibility

Notes

Always pass alt when the avatar identifies a real person or entity. Use empty alt="" only when the avatar is purely decorative and accompanied by visible text.
Initials in fallback should be 1–2 characters.

Composes with

Component	Relation	Note
`AvatarGroup`	`child`	Used inside AvatarGroup for stacked rows.
`PresenceDot`	`sibling`	Render PresenceDot anchored to the avatar.
`ChatMessage`	`child`	Common as the leading slot of a ChatMessage.

Prompt examples

These are the AI prompt → JSX mappings used by the helixui prompt DSL and integrations like Cursor / Claude Code.

user avatar with initials fallback

“avatar for “Sara Tang""

<Avatar src={user.imageUrl} fallback="ST" alt="Sara Tang" />

large avatar in a profile header

“64px avatar in a profile card”

<Avatar size="xl" src={user.imageUrl} fallback="ST" />