Avatar: xtyle components

Slot your own content to override those initials, or use the icon slot for a glyph instead. The prop is userName, not name, because name carries form-participation meaning on an element and an avatar is not a form control. 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; userName names the avatar when there is no image, so it 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

9 props, straight from the manifest.

Prop	Type	Default	Bindings	Description
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.
userName	string	—	html svelte astro	The person the avatar stands for. Derives the fallback initials shown when there is no image and nothing slotted (`"Ada Lovelace"` → `AL`, `"Prince"` → `P`), and names the avatar when no `alt` is given. Named `userName` rather than `name` because `name` is a form-participation attribute on an element. Attribute: `user-name`.
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.
pulse	boolean \| "slow" \| "fast"	—	html svelte astro	Breathe the status dot for a live / online presence: a bare `true` pulses slow, `"fast"` quick. A no-op without `status`, and held still under `prefers-reduced-motion`.

Appearance

Variants

circle

.xtyle-avatar

Fully rounded, the default identity shape.

square

.xtyle-avatar--square

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

Sizes

sm

.xtyle-avatar--sm

Compact, for dense lists.

md

default

.xtyle-avatar

Default.

lg

.xtyle-avatar--lg

Large, for headers.

xl

.xtyle-avatar--xl

Extra large, for profile hero.

States

fallback

.xtyle-avatar__fallback

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

status

.xtyle-avatar__status-dot

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

pulse

.xtyle-avatar--pulse-slow .xtyle-avatar__status-dot

With pulse, the status dot breathes on a soft opacity loop so the avatar reads as live, at a slow or fast cadence; held still under reduced-motion.

Anatomy

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

avatar

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

.xtyle-avatar__image

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

fallback

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

status-dot

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

66/66 consumed tokens produced

default register: 299 tokens

Live coverage check against the xtyle-default register (derive(xtyleDefault, { 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-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

Custom fallback content shown when no image loads. Overrides the initials userName derives — leave it empty and those initials are what you get.

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.

userName names the avatar when there is no alt, so an image-less avatar is announced by the person it stands for rather than by two bare initials.

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.

pulse is decorative motion only, never the carrier of meaning: put the live state in statusLabel ("Online") so it reads the same to assistive tech and under prefers-reduced-motion, where the pulse holds still.

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.

<!-- a photo when one loads -->
<xtyle-avatar user-name="Ada Lovelace" alt="Ada Lovelace" src="/avatars/ada.jpg"></xtyle-avatar>

<!-- no image: the initials fall out of the name ("Grace Hopper" → GH) -->
<xtyle-avatar user-name="Grace Hopper" tone="info" size="lg"></xtyle-avatar>

<xtyle-avatar user-name="Katherine Johnson" tone="purple" shape="square" status="success" status-label="Online"></xtyle-avatar>

<!-- slot your own content to override the derived initials -->
<xtyle-avatar user-name="Project Apollo" tone="warn">🚀</xtyle-avatar>

<xtyle-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>
</xtyle-avatar>

<script lang="ts">
	import { Avatar } from "@xtyle/svelte";
</script>

<!-- a photo when one loads -->
<Avatar userName="Ada Lovelace" alt="Ada Lovelace" src="/avatars/ada.jpg" />

<!-- no image: the initials fall out of the name ("Grace Hopper" → GH) -->
<Avatar userName="Grace Hopper" tone="info" size="lg" />

<Avatar userName="Katherine Johnson" tone="purple" shape="square" status="success" statusLabel="Online" />

<!-- slot your own content to override the derived initials -->
<Avatar userName="Project Apollo" tone="warn">🚀</Avatar>

<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 "@xtyle/astro";
---

<!-- a photo when one loads -->
<Avatar userName="Ada Lovelace" alt="Ada Lovelace" src="/avatars/ada.jpg" />

<!-- no image: the initials fall out of the name ("Grace Hopper" → GH) -->
<Avatar userName="Grace Hopper" tone="info" size="lg" />

<Avatar userName="Katherine Johnson" tone="purple" shape="square" status="success" statusLabel="Online" />

<!-- slot your own content to override the derived initials -->
<Avatar userName="Project Apollo" tone="warn">🚀</Avatar>

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

Live presence

A pulsing status dot reads as online in real time; statusLabel carries the meaning for assistive tech.

<xtyle-avatar user-name="Grace Hopper" status="success" status-label="Online" pulse></xtyle-avatar>

<Avatar userName="Grace Hopper" status="success" statusLabel="Online" pulse />

<Avatar userName="Grace Hopper" status="success" statusLabel="Online" pulse />

Avatar

Initials derived from the name

What fills the chip

Every tone

Sizes, circle and square

Presence status

Live presence

Stacked group

When to use

Props

Appearance

Variants

Sizes

States

Anatomy

Tokens & coverage

Slots

Code

Image, fallback, and status

Live presence

Related

Avatar

Live demo

Initials derived from the name

What fills the chip

Every tone

Sizes, circle and square

Presence status

Live presence

Stacked group

When to use

Props

Appearance

Variants

Sizes

States

Anatomy

Tokens & coverage

Slots

Accessibility

Code

Image, fallback, and status

Live presence

Related