Skip to content

Avatar

A person, agent or source as a round picture or initials, with a corner badge and a group.

<div class="cap-specimen-row">
  <span class="cap-avatar" data-cap="avatar" role="img" aria-label="Alex Rivera" id="av-initials"><span class="cap-avatar-fallback" aria-hidden="true">AR</span></span>
  <span class="cap-avatar" data-cap="avatar" role="img" aria-label="Rosa Park" id="av-picture"><span class="cap-avatar-fallback" aria-hidden="true">RP</span><img class="cap-avatar-image" alt="" width="64" height="64" src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 8 8'%3E%3Crect width='8' height='8' fill='%23b29ae3'/%3E%3Ccircle cx='4' cy='3' r='1.6' fill='%234f2d7f'/%3E%3Cpath d='M1 8a3 3 0 0 1 6 0z' fill='%234f2d7f'/%3E%3C/svg%3E" /></span>
  <span class="cap-avatar" data-cap="avatar" role="img" aria-label="Sam Okafor" id="av-broken"><span class="cap-avatar-fallback" aria-hidden="true">SO</span><img class="cap-avatar-image" alt="" width="64" height="64" src="/missing-avatar.png" /></span>
  <span class="cap-avatar" data-kind="ai" role="img" aria-label="AI"><span class="cap-avatar-fallback" aria-hidden="true">AI</span></span>
</div>

Installation

// package.json: "capsomer": "github:DrDustinEdwards/capsomer#v0.152.2"
import "capsomer/tokens.css";
import "capsomer/base.css";
import "capsomer/avatar.css";
import { enhance } from "capsomer/behavior/avatar";

enhance();

Usage

<span class="cap-avatar" data-cap="avatar" role="img" aria-label="Alex Rivera">
  <span class="cap-avatar-fallback" aria-hidden="true">AR</span>
  <img class="cap-avatar-image" src="/people/alex.jpg" alt="" width="64" height="64" />
</span>

<span class="cap-avatar-group" role="group" aria-label="Contributors">
  <span class="cap-avatar" role="img" aria-label="Alex Rivera">...</span>
  <span class="cap-avatar-count" role="img" aria-label="and 3 more">+3</span>
</span>

Examples

Sizes and square

<div class="cap-specimen-row">
  <span class="cap-avatar" data-size="sm" role="img" aria-label="Small"><span class="cap-avatar-fallback" aria-hidden="true">S</span></span>
  <span class="cap-avatar" role="img" aria-label="Default"><span class="cap-avatar-fallback" aria-hidden="true">D</span></span>
  <span class="cap-avatar" data-size="lg" role="img" aria-label="Large"><span class="cap-avatar-fallback" aria-hidden="true">L</span></span>
  <span class="cap-avatar" data-shape="square" role="img" aria-label="Example Co"><span class="cap-avatar-fallback" aria-hidden="true">EC</span></span>
</div>

With a badge

<div class="cap-specimen-row">
  <span class="cap-avatar" data-size="lg" role="img" aria-label="Alex Rivera, online" id="av-badge"><span class="cap-avatar-fallback" aria-hidden="true">AR</span><span class="cap-avatar-badge" data-tone="ok" aria-hidden="true"><svg viewBox="0 0 16 16" aria-hidden="true"><path fill="none" stroke="currentColor" stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round" d="m3.5 8.5 3 3 6-7" /></svg></span></span>
</div>

Group with a count

<span class="cap-avatar-group" role="group" aria-label="Contributors" id="av-group">
  <span class="cap-avatar" role="img" aria-label="Alex Rivera"><span class="cap-avatar-fallback" aria-hidden="true">AR</span></span>
  <span class="cap-avatar" role="img" aria-label="Rosa Park"><span class="cap-avatar-fallback" aria-hidden="true">RP</span></span>
  <span class="cap-avatar" role="img" aria-label="Sam Okafor"><span class="cap-avatar-fallback" aria-hidden="true">SO</span></span>
  <span class="cap-avatar-count" role="img" aria-label="and 3 more">+3</span>
</span>

Comfortable density

<div class="cap-specimen-row" data-density="comfortable">
  <span class="cap-avatar" role="img" aria-label="Alex Rivera"><span class="cap-avatar-fallback" aria-hidden="true">AR</span></span>
</div>

API reference

Avatar

PropTypeRequiredDoes
namestringYesThe person, agent or source. Always given: it names the avatar for a screen reader when the picture or the initials stand alone.
srcstringA picture; the initials show when there is none or it fails to load.
fallbackstringOverride the initials ("AI" for an agent).
size"sm" | "default" | "lg"
shape"circle" | "square"
kind"person" | "ai""ai" sets the initials in the mono face.
badgeReactNodeA corner badge: a glyph, or a letter, never color alone. Give it a badgeLabel.
badgeLabelstring
badgeTone"ok" | "crit" | "nodata"

AvatarGroup

PropTypeRequiredDoes
labelstringYes
childrenReactNodeYes
extranumber

Functions

FunctionSignatureDoes
enhance(root?: ParentNode): () => void
initials(name?: string | null | undefined, email?: string | null | undefined): stringThe initials for a person: the first and last word's first letters ("Alex Rivera": AR), the first two letters of a one-word name, else the email's first letter, else "?". Whole letters (graphemes), not code units, so an accented or non-Latin name never shows half a letter.

CSS variables

VariableDefault
--cap-avatar-size32px

Parts and data attributes

ClassIs
.cap-avatarthe root
.cap-avatar-badgea part
.cap-avatar-counta part
.cap-avatar-fallbacka part
.cap-avatar-groupa part
.cap-avatar-imagea part
AttributeValues
data-kindai
data-shapesquare
data-sizelg sm
data-stateerror
data-tonecrit nodata ok

Accessibility

An avatar is not a control and takes no keys. One that opens a profile is wrapped in a link or button by the caller, which owns its focus ring.

  • The avatar is role="img" with the person's name as aria-label; the picture is alt="" and the initials are aria-hidden, so the name is read once.
  • A group is role="group" named by aria-label; the count is an image named "and 3 more".
  • The fallback reaches 4.5:1; the badge's glyph reaches 3:1 on its fill.