Examples
Basic usage
JD
<div class="cluster">
<div class="avatar">
<img src="https://picsum.photos/seed/jane/96/96" alt="Jane Doe" />
</div>
<div class="avatar">
<span>JD</span>
</div>
<div class="avatar">
<svg
xmlns="http://www.w3.org/2000/svg"
viewBox="0 0 24 24"
fill="none"
stroke="currentColor"
stroke-width="2"
stroke-linecap="round"
stroke-linejoin="round"
aria-hidden="true"
>
<path d="M20 21v-2a4 4 0 0 0-4-4H8a4 4 0 0 0-4 4v2" />
<circle cx="12" cy="7" r="4" />
</svg>
</div>
</div>
Sizes
SM
MD
LG
XL
<div class="cluster">
<div class="avatar is-sm"><span>SM</span></div>
<div class="avatar"><span>MD</span></div>
<div class="avatar is-lg"><span>LG</span></div>
<div class="avatar is-xl"><span>XL</span></div>
</div>
Shapes
AC
<div class="cluster">
<div class="avatar">
<img src="https://picsum.photos/seed/circle/96/96" alt="Circular user avatar" />
</div>
<div class="avatar is-square">
<img src="https://picsum.photos/seed/square/96/96" alt="Square team avatar" />
</div>
<div class="avatar is-square"><span>AC</span></div>
</div>
Status indicator
OF
Status dot's ring picks up the card surface.
<div class="cluster">
<div class="avatar">
<img src="https://picsum.photos/seed/u1/96/96" alt="Online user" />
<span class="avatar-status is-online" aria-label="Online"></span>
</div>
<div class="avatar">
<img src="https://picsum.photos/seed/u2/96/96" alt="Away user" />
<span class="avatar-status is-away" aria-label="Away"></span>
</div>
<div class="avatar">
<img src="https://picsum.photos/seed/u3/96/96" alt="Busy user" />
<span class="avatar-status is-busy" aria-label="Busy"></span>
</div>
<div class="avatar">
<span>OF</span>
<span class="avatar-status is-offline" aria-label="Offline"></span>
</div>
</div>
<div class="card cluster" style="--avatar-status-ring-color: var(--color-surface-raised)">
<div class="avatar">
<img src="https://picsum.photos/seed/c1/96/96" alt="Online user" />
<span class="avatar-status is-online" aria-label="Online"></span>
</div>
<div>
<p>Status dot's ring picks up the card surface.</p>
</div>
</div>
Group
+4
Reviewed by
<div class="avatar-group" aria-label="Team: Alex, Sam, Casey, and 4 others">
<div class="avatar"><img src="https://picsum.photos/seed/g1/96/96" alt="" /></div>
<div class="avatar"><img src="https://picsum.photos/seed/g2/96/96" alt="" /></div>
<div class="avatar"><img src="https://picsum.photos/seed/g3/96/96" alt="" /></div>
<div class="avatar"><span>+4</span></div>
</div>
<div class="card" style="--avatar-group-border-color: var(--color-surface-raised)">
<div>
<div class="flow flow-space-xs">
<p class="text-muted">Reviewed by</p>
<div class="avatar-group" aria-label="Reviewers: Alex, Sam, Casey">
<div class="avatar is-sm">
<img src="https://picsum.photos/seed/r1/64/64" alt="" />
</div>
<div class="avatar is-sm">
<img src="https://picsum.photos/seed/r2/64/64" alt="" />
</div>
<div class="avatar is-sm">
<img src="https://picsum.photos/seed/r3/64/64" alt="" />
</div>
</div>
</div>
</div>
</div>
</div>
Customization
JD
AM
RK
PT
<div class="cluster">
<div
class="avatar"
style="--avatar-bg: oklch(85% 0.12 30); --avatar-color: oklch(30% 0.15 30)"
>
<span>JD</span>
</div>
<div
class="avatar"
style="--avatar-bg: oklch(85% 0.12 130); --avatar-color: oklch(30% 0.15 130)"
>
<span>AM</span>
</div>
<div
class="avatar"
style="--avatar-bg: oklch(85% 0.12 230); --avatar-color: oklch(30% 0.15 230)"
>
<span>RK</span>
</div>
<div
class="avatar"
style="--avatar-bg: oklch(85% 0.12 330); --avatar-color: oklch(30% 0.15 330)"
>
<span>PT</span>
</div>
</div>
Source comments
Avatar -- user or entity image with fallback initials or icon (extra).
The status dot has no inherent semantics -- consumers add
aria-label="Online" (or similar) on the dot, or describe the
state in adjacent text, depending on the surrounding pattern.
Markup:
<div class="avatar"><img src="..." alt="Jane Doe"></div>
<div class="avatar"><span>JD</span></div>
<div class="avatar"><svg aria-hidden="true">...</svg></div>
<div class="avatar">
<img src="..." alt="Jane Doe">
<span class="avatar-status is-online" aria-label="Online"></span>
</div>
<div class="avatar-group" aria-label="Team: Alex, Sam, Casey, +4 others">
<div class="avatar"><img src="..." alt="Alex"></div>
<div class="avatar"><img src="..." alt="Sam"></div>
<div class="avatar"><img src="..." alt="Casey"></div>
<div class="avatar"><span>+4</span></div>
</div>
Archetype: Atom (P3). Pure CSS, no JS. Image / initials / icon
children are styled via descendant selectors (P6 composition --
structure in markup, theming via descendants of the .avatar root).
Default bg / color: neutral fill (--color-fill-strong /
--color-text-muted). The disc is content surface, not chrome --
but defaulting to a neutral tier lets consumers override
--avatar-bg per-instance for hash-by-name color variety without
overriding a primary-tinted default.
Group stacking: source order = visual order, source-last paints
on top of the overlap. The conventional "+N" overflow indicator
lands rightmost AND on top with no extra wiring. Consumers that
want first-on-top can layer z-index per item; not a default.
Status dot ring: defaults to --color-surface. Inside a card or
any --color-surface-raised container, override
--avatar-status-ring-color on the avatar (or a parent) to match the
surrounding background -- otherwise the near-white ring stays
visible against the card.
Reference
Source: src/css/extras/avatar.css
Applies to
.avatar
Classes
| Class | Kind | Description |
|---|---|---|
.is-sm | variant | Small size variant (1.75rem) |
.is-lg | variant | Large size variant (3.5rem) |
.is-xl | variant | Extra-large size variant (5rem) |
.is-square | variant | Square shape for entity or team avatars |
Tokens
| Token | Default | Description |
|---|---|---|
--avatar-size | 2.5rem | Diameter of the avatar disc |
--avatar-radius | var(--radius-pill) | Corner radius of the avatar |
--avatar-bg | var(--color-fill-strong) | Background color for the avatar disc |
--avatar-color | var(--color-text-muted) | Text and icon color inside the avatar |
--avatar-status-size | calc(var(--avatar-size) * 0.3) | Diameter of the status indicator dot |
--avatar-status-ring-color | var(--color-surface) | Ring color around the status dot for background separation |
Related: Avatar Status
Status indicator dot
Source: src/css/extras/avatar.css
Applies to
.avatar-status
Classes
| Class | Kind | Description |
|---|---|---|
.is-online | variant | Online status, colored with success |
.is-away | variant | Away status, colored with warning |
.is-busy | variant | Busy status, colored with danger |
.is-offline | variant | Offline status, colored with subtle text |
Related: Avatar Group
Overlapping stack of avatars
Source: src/css/extras/avatar.css
Applies to
.avatar-group
Tokens
| Token | Default | Description |
|---|---|---|
--avatar-group-offset | -0.75rem | Negative inline margin for avatar overlap |
--avatar-group-border-color | var(--color-surface) | Border color between overlapping avatars for visual separation |