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/1c608019/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 (sm = 32px, md = 40px, lg = 48px, xl = 64px). The avatar is always a perfect circle.

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 variant="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.

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
`size`	string	`'md'`	`xs`, `sm`, `md`, `lg`, `xl`
`shape`	string	`'circle'`	`circle`, `square`
`status`	string\|null	`null`	`online`, `busy`, `away`, `offline`
`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 (`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.
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'],
],