Avatar

A circular user/entity avatar showing an image or initials fallback, with optional presence dot and square variant for projects/apps. A size class is mandatory — the base class sets no dimensions. Use .avatar-group to overlap several avatars (watchers, assignees).

Root: .avatar on <span>

Examples

Example 1

<span class="avatar avatar-md"><img src="dana.png" alt="Dana K"></span>

Example 2

<span class="avatar avatar-md avatar-online">JC</span>

Authoring tags — <lz-avatar>

JC P

Authoring source

<lz-avatar presence="online">JC</lz-avatar>
<lz-avatar size="lg" square>P</lz-avatar>

Expands to

<span class="avatar avatar-md avatar-online" data-lz="avatar" data-lz-version="0.1.0">JC</span>
<span class="avatar avatar-lg avatar-square" data-lz="avatar" data-lz-version="0.1.0">P</span>

Authoring tags are macro-expanded to the canonical HTML above at build time (Vite plugin or lz-expand CLI) — the shipped artifact has no runtime.

Contract

Variants & modifiers

Class	Axis	Rules
`avatar-xs`	size	one required · exclusive
`avatar-sm`	size	one required · exclusive
`avatar-md`	size	one required · exclusive
`avatar-lg`	size	one required · exclusive
`avatar-xl`	size	one required · exclusive
`avatar-online`	presence	optional · exclusive
`avatar-busy`	presence	optional · exclusive
`avatar-offline`	presence	optional · exclusive
`avatar-square`	modifier	optional

Structure

Selector	Required	Description
`img`	optional	Optional photo; fills the avatar with object-fit: cover. Omit it and put 1-2 characters of text content for the initials fallback.

Accessibility

On	Attribute	Level	When
`img`	`alt`	required

Initials alone don't identify a person to assistive tech; provide the full name via img alt, adjacent visible text, or aria-label on the avatar. Presence dots (online/busy/offline) are color-only ::after pseudo-elements — convey presence in text too where it matters. avatar-group truncation counters ("+4") are plain avatars; label the group, e.g. aria-label="7 watchers".

Nesting

Allowed in:

.navbar-actions
.issue-card-meta (placed last — it right-aligns via margin-left:auto)
.sidebar-header
table cells
.avatar-group

Never inside (or containing):

.avatar

Subcomponents

Avatar-group

Overlapping horizontal stack of avatars, each gaining a surface-colored ring; consecutive avatars overlap by 8px.

Root: .avatar-group on <span>, <div>

Example

AB+4

<span class="avatar-group"><span class="avatar avatar-md">A</span><span class="avatar avatar-md">B</span><span class="avatar avatar-md">+4</span></span>

Structure

Selector	Required	Description
`.avatar`	required	One or more .avatar children (each still needs its size class; use the same size for all).

Accessibility

Label the stack as a whole (e.g. aria-label="Watchers: Alex, Bo, Cam and 4 others") rather than relying on per-avatar initials.

Nesting

Allowed in:

table cells
card meta rows
toolbars

Never inside (or containing):

.avatar-group