Avatar

User image or initials fallback — sizes sm, md, and lg.

Preview

Live

Demo user 
<span class="avatar avatar--md" role="img" aria-label="Grace Hopper">
  <span class="avatar__initials" aria-hidden="true">GH</span>
</span>

<span class="avatar avatar--md">
  <img class="avatar__img" src="/avatar.jpg" alt="Demo user" />
</span>

Variants

Small

.avatar--sm — dense lists and chips.

Medium

.avatar--md — default size.

Large

.avatar--lg — profile headers.

Image

.avatar__img with meaningful alt; React falls back to initials on load error.

Demo user

Accessibility

  • Initials-only avatars need an accessible name via aria-label or React label / aria-label, with role="img".
  • When showing an image, put the name in alt on the <img> — do not also set role="img" on the wrapper.
  • Visible initials marked aria-hidden="true" when the root already has a name.
  • Prefer short initials (1–2 characters) for legibility at small sizes.

API

HTML classes

Class Description
.avatar Root pill container.
.avatar--sm / --md / --lg Size modifiers.
.avatar__img Cover-fit image.
.avatar__initials Fallback initials layer.

React props

From src/core/Avatar.tsx — extends HTMLAttributes<HTMLSpanElement> (minus children).

Prop Type Default Description
size 'sm' | 'md' | 'lg' 'md' Maps to .avatar--*.
src string — Image URL; requires alt.
alt string — Required when src is set.
initials string — Shown without image or after load error.
label / aria-label string — Required accessible name for initials-only.
className string — Merged onto the root.