LayoutUI
Theme Presets
Browse Components

Avatar

Represent people and teams with images or initials.

Basic

Initials provide a recognizable fallback without an image.

View Code
HTML
<span class="avatar" role="img" aria-label="Alex Morgan">
  <span class="avatar-fallback" aria-hidden="true">
    AM
  </span>
</span>

Image

The image appears after loading. Its fallback stays available when the image cannot load.

View Code
HTML
<span class="avatar " role="img" aria-label="Layout UI">
  <span class="avatar-fallback" aria-hidden="true">
    UI
  </span>
  <img src="/images/apple-touch-icon.png" alt="" width="40" height="40" hidden>
</span>

Sizes

Small, default and large avatars use 32px, 40px and 56px.

View Code
HTML
<div class="cluster">
  <span class="avatar avatar-small" role="img" aria-label="Alex Morgan">
    <span class="avatar-fallback" aria-hidden="true">
      AM
    </span>
  </span>
  <span class="avatar" role="img" aria-label="Alex Morgan">
    <span class="avatar-fallback" aria-hidden="true">
      AM
    </span>
  </span>
  <span class="avatar avatar-large" role="img" aria-label="Alex Morgan">
    <span class="avatar-fallback" aria-hidden="true">
      AM
    </span>
  </span>
</div>

Rounded

Rounded avatars follow the theme control radius.

View Code
HTML
<span class="avatar avatar-rounded" role="img" aria-label="Sam Rivera">
  <span class="avatar-fallback" aria-hidden="true">
    SR
  </span>
</span>

Unknown person

Use the shared user icon when no name or image is available.

View Code
HTML
<span class="avatar " role="img" aria-label="Unknown person">
  <span class="avatar-fallback" aria-hidden="true">
    <svg
      xmlns="http://www.w3.org/2000/svg"
      viewbox="0 0 24 24"
      fill="none"
      stroke="currentColor"
      stroke-width="1.75"
      stroke-linecap="round"
      stroke-linejoin="round"
      class="icon"
      aria-hidden="true"
      focusable="false"
    >
      <circle cx="12" cy="7" r="4">
      </circle>
      <path d="M5 21v-2a4 4 0 0 1 4-4h6a4 4 0 0 1 4 4v2">
      </path>
    </svg>
  </span>
</span>

With a name

Avoid repeating the name to screen readers when it is already visible.

Alex Morgan

Product designer

View Code
HTML
<div class="avatar-profile">
  <span class="avatar" aria-hidden="true">
    <span class="avatar-fallback" aria-hidden="true">
      AM
    </span>
  </span>
  <div>
    <p>
      Alex Morgan
    </p>
    <p class="muted">
      Product designer
    </p>
  </div>
</div>

Group

Overlap a small collection and label any additional members.

View Code
HTML
<div class="avatar-group" role="group" aria-label="Project team">
  <span class="avatar " role="img" aria-label="Alex Morgan">
    <span class="avatar-fallback" aria-hidden="true">
      AM
    </span>
  </span>
  <span class="avatar " role="img" aria-label="Sam Rivera">
    <span class="avatar-fallback" aria-hidden="true">
      SR
    </span>
  </span>
  <span class="avatar " role="img" aria-label="Jamie Chen">
    <span class="avatar-fallback" aria-hidden="true">
      JC
    </span>
  </span>
  <span class="avatar " role="img" aria-label="3 more team members">
    <span class="avatar-fallback" aria-hidden="true">
      +3
    </span>
  </span>
</div>

Right-to-left

Groups follow the reading direction.

View Code
HTML
<div dir="rtl">
  <div class="avatar-group" role="group" aria-label="Project team">
    <span class="avatar " role="img" aria-label="Alex Morgan">
      <span class="avatar-fallback" aria-hidden="true">
        AM
      </span>
    </span>
    <span class="avatar " role="img" aria-label="Sam Rivera">
      <span class="avatar-fallback" aria-hidden="true">
        SR
      </span>
    </span>
    <span class="avatar " role="img" aria-label="Jamie Chen">
      <span class="avatar-fallback" aria-hidden="true">
        JC
      </span>
    </span>
    <span class="avatar " role="img" aria-label="3 more team members">
      <span class="avatar-fallback" aria-hidden="true">
        +3
      </span>
    </span>
  </div>
</div>

Installation

Download these files into the matching paths in your project, or use Create to assemble a kit. Include each dependency once. Do not also load app.css.

base.cssavatar.cssavatar.js
Add to your page
<link rel="stylesheet" href="/library/assets/base.css">
<link rel="stylesheet" href="/library/assets/avatar.css">
<script defer src="/library/assets/avatar.js"></script>

9,573 bytes CSS including base · 899 bytes runtime JavaScript

Usage

Identity and fallbacks

Use span.avatar with role=img and aria-label containing the full name. Put one or two initials in .avatar-fallback with aria-hidden=true, or use the shared user icon for an unknown person. Supply initials yourself; do not infer them from arbitrary names. For an image, add a direct img child with src, alt="", width, height and hidden, then load avatar.js. The initials remain visible until the image loads and return if it fails; no JavaScript retains the fallback. Use avatar-small (32px), default (40px), avatar-large (56px), or --avatar-size. avatar-rounded follows the theme control radius. Compose avatar-group with an accessible group name; a +N remainder is static text, not a button. Use aria-hidden=true and omit role/name when adjacent text already identifies the person. Avatars are noninteractive; wrap in a named native button or link with a 44px target when an action is needed. Use layoutAvatar.refresh(root) after mounting and destroy(avatar) before removal. Applications own profile data, image URLs and navigation; no uploads, status tracking or initials generation.

Images and themes

Use trusted image URLs and crop deliberately with object-fit/object-position. Supply a meaningful fallback and keep identity available without color or images. Example profile names are fictional; the image example uses the Layout UI logo.

Building with AI? The AI Manifest has these notes and the full contract. See the AI Guide.