Skip to main content
xoji

Avatar
Info:Display html svelte astro Success: coverage 67/67

An identity chip: a photo when one loads, a tinted initials-or-icon fallback when it doesn't.

Live demo

live · @xoji/astro

Avatar

Initials fallback across tones
AL GH KJ RM BL MH

Every tone

Accents
AC AC AC AC NE

Statuses
SU IN WA DA

Named hues
RE OR YE GR BL PU BR PI CY GR WH BL

Sizes, circle and square
AL AL AL AL
GH GH GH GH

Presence status
TM

success
TM

warn
TM

danger
TM

neutral

Icon fallback and stacked group
AL GH KJ RM +5

Avatar presents a person or entity as a compact square or circle. Given a src, it shows the image, cover-cropped to fill; if the image is absent or fails to load, it falls back to the slotted content (initials as text, or an icon via the icon slot) on a soft, hue-tinted background.

The fallback tint follows tone, which accepts any of the six semantic roles or the twelve named hues, so a deterministic per-user color is a one-attribute choice. Four sizes (sm, md, lg, xl), two shapes (circle, square), and an optional corner status dot in any semantic tone round out the surface. alt names the image; the fallback text stays in the accessibility tree so the avatar is announced either way.

When to use

How this component composes with the rest of the set.

Stack a row of avatars into an avatar group; negative inline margin overlaps them.
Pair with Badge for a labeled identity row, or with the status dot for presence.
Feed tone a hash of the user id to get a stable, distinct fallback color per person.

Props

7 props, straight from the manifest.

PropTypeDefaultBindingsDescription
src string —
html svelte astro
The image URL. When absent or failed, the fallback content shows instead.
alt string —
html svelte astro
Accessible name for the image. Required when `src` is set; also labels the fallback.
tone FullTone
accent neutral danger success warn info accent-2 accent-3 accent-4 red orange yellow green blue purple brown pink cyan gray white black
neutral
html svelte astro
Soft-tint color for the fallback background — any semantic role, accent variant, or named hue.
size AvatarSize
sm md lg xl
md
html svelte astro
Chip size.
shape AvatarShape
circle square
circle
html svelte astro
Outline shape: a circle or a rounded square.
status Tone
accent neutral danger success warn info
—
html svelte astro
When set, shows a corner status dot in this semantic tone.
statusLabel string —
html svelte astro
Accessible name for the status dot (e.g. "Online"); announced as additional avatar text.

Appearance

Variants

circle

 .xoji-avatar

Fully rounded, the default identity shape.

square

 .xoji-avatar--square

A rounded square, for entities and projects rather than people.

Sizes

sm
.xoji-avatar--sm

Compact, for dense lists.

md

 default
.xoji-avatar

Default.

lg
.xoji-avatar--lg

Large, for headers.

xl
.xoji-avatar--xl

Extra large, for profile hero.

States

fallback

 .xoji-avatar__fallback

No image: the tinted initials-or-icon stand-in fills the chip.

status

 .xoji-avatar__status-dot

A corner dot conveys presence; its color is the chosen status tone, ringed in the surface.

Anatomy

The named parts that make up the component, with their selectors.

avatar

 .xoji-avatar

The root chip carrying the size, shape, and tone classes; sizes the image and fallback and anchors the status dot.
--space-7 --font-sans --text-sm --weight-semibold --leading-tight --neutral-text --radius-full

image

 .xoji-avatar__image

The portrait image, cover-cropped to fill the chip and clipped to the chip's shape.

fallback

 .xoji-avatar__fallback

The initials-or-icon stand-in shown when no image is present, painted with the tone's soft tint.
--neutral-bg --neutral-text --space-0

status-dot

 .xoji-avatar__status-dot

The optional corner indicator, ringed in the surface color so it reads against any background.
--space-2 --neutral --radius-full --border-thick --bg-1

Tokens & coverage

What the component consumes, checked live against what the algorithm produces.

Success:fully covered 67/67 consumed tokens produced default register: 276 tokens

Live coverage check against the xoji-default register (derive(xojiDefault, { anchors }) → coverComponent(manifest, register)). Every token this component consumes must be a key the algorithm produces.

--accent --accent-2-bg --accent-2-text --accent-3-bg --accent-3-text --accent-4-bg --accent-4-text --accent-bg --accent-text --bg-1 --black-bg --black-text --blue-bg --blue-text --border-thick --brown-bg --brown-text --cyan-bg --cyan-text --danger --danger-bg --danger-text --font-sans --gray-bg --gray-text --green-bg --green-text --info --info-bg --info-text --leading-tight --neutral --neutral-bg --neutral-text --orange-bg --orange-text --pink-bg --pink-text --purple-bg --purple-text --radius-full --radius-lg --radius-md --radius-sm --red-bg --red-text --space-0 --space-2 --space-4 --space-6 --space-7 --space-8 --success --success-bg --success-text --text-body --text-lg --text-sm --text-xs --warn --warn-bg --warn-text --weight-semibold --white-bg --white-text --yellow-bg --yellow-text

Slots
default
html svelte astro

Fallback initials shown when no image loads.
icon
html svelte astro

An icon fallback, used in place of initials when no image loads.

Accessibility
The image carries alt; the binding warns at runtime when src is set without it.
When the image is absent or errors, the fallback initials or aria-label'd icon remain in the accessibility tree so the avatar is still announced.
The decorative status dot is aria-hidden; its meaning rides on statusLabel as visually-hidden text in the accessibility tree.
The fallback icon slot is decorative. Provide alt (or fallback initials) so the avatar still has a name.

Code

Image, fallback, and status

A photo when one loads, tinted initials or an icon when it doesn't, with an optional presence dot.

 
<xoji-avatar alt="Ada Lovelace" src="/avatars/ada.jpg"></xoji-avatar>

<xoji-avatar alt="Grace Hopper" tone="info" size="lg">GH</xoji-avatar>

<xoji-avatar alt="Project Apollo" tone="purple" shape="square" status="success"></xoji-avatar>

<xoji-avatar alt="Unknown user" size="xl">
	<svg slot="icon" viewBox="0 0 24 24" aria-hidden="true">
		<path fill="currentColor" d="M12 12a5 5 0 1 0 0-10 5 5 0 0 0 0 10Zm0 2c-5 0-9 2.5-9 6v2h18v-2c0-3.5-4-6-9-6Z" />
	</svg>
</xoji-avatar>
 
<script lang="ts">
	import { Avatar } from "@xoji/svelte";
</script>

<Avatar alt="Ada Lovelace" src="/avatars/ada.jpg" />

<Avatar alt="Grace Hopper" tone="info" size="lg">GH</Avatar>

<Avatar alt="Project Apollo" tone="purple" shape="square" status="success" />

<Avatar alt="Unknown user" size="xl">
	{#snippet icon()}
		<svg viewBox="0 0 24 24" aria-hidden="true">
			<path fill="currentColor" d="M12 12a5 5 0 1 0 0-10 5 5 0 0 0 0 10Zm0 2c-5 0-9 2.5-9 6v2h18v-2c0-3.5-4-6-9-6Z" />
		</svg>
	{/snippet}
</Avatar>
 
---
import { Avatar } from "@xoji/astro";
---

<Avatar alt="Ada Lovelace" src="/avatars/ada.jpg" />

<Avatar alt="Grace Hopper" tone="info" size="lg">GH</Avatar>

<Avatar alt="Project Apollo" tone="purple" shape="square" status="success" />

<Avatar alt="Unknown user" size="xl">
	<svg slot="icon" viewBox="0 0 24 24" aria-hidden="true">
		<path fill="currentColor" d="M12 12a5 5 0 1 0 0-10 5 5 0 0 0 0 10Zm0 2c-5 0-9 2.5-9 6v2h18v-2c0-3.5-4-6-9-6Z" />
	</svg>
</Avatar>