Avatar

A user profile image with automatic fallback to initials or a default icon. Avatars support five sizes, two shapes, and optional status indicators.

Basic Usage

With image

<x-wirekit::avatar src="/placeholder/80x80?bg=4f46e5&fg=ffffff&label=JS&gradient=none" alt="Jane Smith" />

With initials

<x-wirekit::avatar initials="JS" alt="Jane Smith" />

Default fallback icon

<x-wirekit::avatar alt="Anonymous user" />

Fallback Chain

The avatar tries each fallback in order:

Image (src prop) — rendered as <img>
Initials (initials prop) — centered text
Default icon — generic user silhouette SVG

Sizes

All sizes

XS SM MD LG XL

<x-wirekit::avatar size="xs" initials="XS" />
<x-wirekit::avatar size="sm" initials="SM" />
<x-wirekit::avatar size="md" initials="MD" />
<x-wirekit::avatar size="lg" initials="LG" />
<x-wirekit::avatar size="xl" initials="XL" />

Shapes

Circle and square

JD JD

<x-wirekit::avatar shape="circle" initials="JD" size="lg" />
<x-wirekit::avatar shape="square" initials="JD" size="lg" />

Status Indicators

Add a status dot to indicate user presence. The dot sits on the bottom-right corner with a ring matching the page background:

Status dots (default)

ON BS AW OF

<x-wirekit::avatar initials="ON" status="online" size="lg" />
<x-wirekit::avatar initials="BS" status="busy" size="lg" />
<x-wirekit::avatar initials="AW" status="away" size="lg" />
<x-wirekit::avatar initials="OF" status="offline" size="lg" />

Set status-variant="ring" to replace the corner dot with a colored ring that surrounds the entire avatar, separated from the image by a thin gap in the page background. This produces a "double ring" presence indicator similar to Slack, Discord or iMessage — useful when you want the status to be visible at a glance without hunting for a tiny dot:

Status ring — all four states

ON BS AW OF

<x-wirekit::avatar initials="ON" status="online" status-variant="ring" size="lg" />
<x-wirekit::avatar initials="BS" status="busy" status-variant="ring" size="lg" />
<x-wirekit::avatar initials="AW" status="away" status-variant="ring" size="lg" />
<x-wirekit::avatar initials="OF" status="offline" status-variant="ring" size="lg" />

The ring scales subtly with avatar size so it stays visually balanced on every size variant:

Status ring across sizes

XS SM MD LG XL

<x-wirekit::avatar initials="XS" status="online" status-variant="ring" size="xs" />
<x-wirekit::avatar initials="SM" status="online" status-variant="ring" size="sm" />
<x-wirekit::avatar initials="MD" status="online" status-variant="ring" size="md" />
<x-wirekit::avatar initials="LG" status="online" status-variant="ring" size="lg" />
<x-wirekit::avatar initials="XL" status="online" status-variant="ring" size="xl" />

When status-variant="ring", the corner dot is omitted — the colored ring on the container already conveys the presence state, and stacking both would be visually noisy. The name moves with it: instead of the dot's aria-label, the avatar carries a visually hidden text span holding the same word, so screen readers still announce the state once.

Width & Layout

Avatar dimensions are fixed by the size prop (xs = 24px, sm = 32px, md = 40px, lg = 48px, xl = 64px). The outline is a perfect circle by default; shape="square" swaps it for --radius-wk-md, which is the pair previewed above.

Deterministic Color From Initials

Add from-initials to derive a stable background color from the initials hash — the same person always gets the same color. The palette pairs an AA-contrast background with white text and is theme-independent.

Avatars colored from initials

AB MP LK SR

<x-wirekit::row gap="sm" wrap>
    <x-wirekit::avatar initials="AB" from-initials />
    <x-wirekit::avatar initials="MP" from-initials />
    <x-wirekit::avatar initials="LK" from-initials />
    <x-wirekit::avatar initials="SR" from-initials />
</x-wirekit::row>

The same palette is available in PHP, so a custom chip or inline badge can match an avatar without rendering one:

use Pushery\WireKit\WireKit;

// Returns ['bg' => 'oklch(...)', 'fg' => '#fff'] for the same initials the component hashes.
$palette = WireKit::avatarPaletteFor('AB');

With Name & Detail

Compose an avatar with a name and a secondary line (role, email, handle) using Row and Stack — the canonical "user identity" cell for menus, tables, and comment headers.

Avatar with name and detail

Jane Doe

Product Designer

<x-wirekit::row gap="sm" align="center">
    <x-wirekit::avatar initials="JD" from-initials />
    <x-wirekit::stack gap="none">
        <x-wirekit::text weight="semibold">Jane Doe</x-wirekit::text>
        <x-wirekit::text intent="muted" size="sm">Product Designer</x-wirekit::text>
    </x-wirekit::stack>
</x-wirekit::row>

Avatar Group

Stack multiple avatars into an overlapping group with <x-wirekit::avatar.group>. Each avatar is ringed in the surface color so the discs read as distinct. Set :remaining for a trailing "+N" overflow chip, and label for the group's accessible name. Match the group's size to the avatars you place inside it.

An avatar that the next one overlaps sets its initials in the part of its disc that stays visible, so the next disc never covers a letter. Groups in xs and sm overlap a fifth of the disc, larger ones 0.6rem. To change the overlap, set --wk-avatar-group-overlap on the group, and the initials follow it. At xs two wide letters such as "MW" fill nearly the whole disc and lose their outer edges in a stack, so one initial reads better at that size.

Overlapping avatar group with overflow count

AB MP LK

<x-wirekit::avatar.group label="5 collaborators" :remaining="2">
    <x-wirekit::avatar initials="AB" from-initials />
    <x-wirekit::avatar initials="MP" from-initials />
    <x-wirekit::avatar initials="LK" from-initials />
</x-wirekit::avatar.group>

Avatar group sizes

AB MP LK

AB MP

<x-wirekit::stack gap="md">
    <x-wirekit::avatar.group size="sm" label="Small team">
        <x-wirekit::avatar size="sm" initials="AB" from-initials />
        <x-wirekit::avatar size="sm" initials="MP" from-initials />
        <x-wirekit::avatar size="sm" initials="LK" from-initials />
    </x-wirekit::avatar.group>
    <x-wirekit::avatar.group size="lg" label="Large team" :remaining="4">
        <x-wirekit::avatar size="lg" initials="AB" from-initials />
        <x-wirekit::avatar size="lg" initials="MP" from-initials />
    </x-wirekit::avatar.group>
</x-wirekit::stack>

Props

Prop	Type	Default	Description
`src`	string\|null	`null`	Image URL
`alt`	string\|null	`null`	Accessible name (for images AND initials/icon fallbacks)
`initials`	string\|null	`null`	Text shown when no `src` is provided
`fromInitials`	bool	`false`	With `initials` set and no `src`, derive the background color deterministically from the initials, so the same person always gets the same color. The palette pairs an AA-contrast background with white text and is theme-independent
`size`	string	`'md'`	`xs`, `sm`, `md`, `lg`, `xl`
`shape`	string	`'circle'`	`circle`, `square`
`status`	string\|null	`null`	`online`, `busy`, `away`, `offline`
`statusVariant`	string	`'dot'`	How the status reads: `dot` (a corner dot) or `ring` (a ring around the whole avatar — more prominent, which is what a dense roster wants). Ignored when `status` is null
`scope`	string\|null	`null`	Scoped personalization name

`<x-wirekit::avatar.group>`

Prop	Type	Default	Description
`remaining`	int\|null	`null`	Renders a trailing "+N" overflow chip when greater than 0
`size`	string	`'md'`	Sizes the overflow chip to match the avatars, and sets how far they overlap (`xs`–`xl`)
`label`	string\|null	`null`	Accessible name for the group
`scope`	string\|null	`null`	Scoped personalization name

Accessibility

Always provide an alt prop. For <img> avatars, this becomes the alt attribute. For initials/icon fallbacks, it's rendered as visually hidden text (sr-only) so screen readers announce the person's name — not just their initials.
Status indicators are named, and the name is translated. The dot carries role="img" plus an aria-label — an icon that conveys information, not a live region, so it is read wherever the avatar itself is read rather than only at the moment it appears. The ring variant uses visually hidden text instead. The four words ("Online", "Busy", "Away", "Offline") come from WireKit's translation catalog and follow your application's locale.
The dot and the ring tell the four states apart by color alone. Where the state matters to the reader, show it as text as well, beside the name for instance. WCAG 1.4.1 asks for a second visible cue besides color.
Initials are marked aria-hidden="true" when an alt is provided, preventing duplicate announcements.

Accessibility examples

{{-- Good: clear identity --}}
<x-wirekit::avatar src="/users/jane.jpg" alt="Jane Smith" />

{{-- Good: name announced via alt, initials hidden --}}
<x-wirekit::avatar initials="JS" alt="Jane Smith" />

{{-- Decorative (e.g. in a list with visible name next to it): --}}
<x-wirekit::avatar initials="JS" />

Keyboard Interaction

This component is purely presentational and does not respond to keyboard input.

Pitfalls

Don't use an avatar without alt. Decorative use is fine with alt=""; identifying use needs the person's name in alt or it's not announced.

Design Tokens

Token	Purpose
`--color-wk-bg-muted`	Fallback background (initials + icon)
`--color-wk-text`	Initials text color
`--color-wk-text-muted`	Default icon color
`--color-wk-border-subtle`	Avatar border
`--color-wk-success` / `--color-wk-warning` / `--color-wk-danger` / `--color-wk-text-muted`	Status colors
`--color-wk-bg-elevated`	Status dot ring color
`--radius-wk-md`	Square avatar radius

Customization

Override defaults in config/wirekit.php:

'components' => [
    'avatar' => ['size' => 'lg', 'shape' => 'square'],
],