Avatar and Avatar Group

Who someone is, as a photo, initials or an icon in a shape.

<span class="avatar" role="img" aria-label="Sam Rivera">SR</span>

Why it exists

A face or a pair of initials lets someone spot a person in a thread or a member list without reading every name. That’s the whole job, so an Avatar is only a shape that holds a photo, initials or an icon.

It is never a control. A picture of someone doesn’t say what pressing it will do, so a Button or a Link wraps it and carries the name.

How it’s named depends on where it sits. Beside a visible name it’s hidden, because hearing the same name twice helps nobody. On its own it has to carry the name itself. That’s the one thing to get right each time.

When to use

• For a person or an account: in a comment, a member list or an account Menu.
• Not for a thing: album art or a product shot is a Thumbnail.
• Not for an icon on a tint: that is an Icon Box.

Rules

• An Avatar is never interactive. A Button or link that opens a profile contains one, and the control carries the name.
• Naming follows context. Beside a visible name, as in a Lockup: aria-hidden="true", and an image inside takes alt="". On its own with a photo: the alt names it. On its own with initials or an icon: role="img" and aria-label.
• Presence is never colour alone. A dot Badge in the bottom corner, hidden from screen readers, with the state in the name (“Sam Rivera, online”) or in visible text.

Name It for Where It Sits

SR

Code

HTML

<!-- Initials on their own -->
<span class="avatar" role="img" aria-label="Sam Rivera">SR</span>

<!-- A photo on its own -->
<img class="avatar" src="/examples/thumb.svg" alt="Ade Okafor" />

<!-- An icon -->
<span class="avatar" role="img" aria-label="Guest">
  <svg class="icon" width="1em" height="1em" aria-hidden="true" focusable="false"><use href="#User"/></svg>
</span>

<!-- Presence: a photo inside a span so the badge can sit on it -->
<span class="avatar" role="img" aria-label="Sam Rivera, online">
  <img src="/examples/thumb.svg" alt="" />
  <span class="badge badge--dot badge--success badge--bottom-end" aria-hidden="true"></span>
</span>

In a Control

Code

HTML

<button type="button" class="button button--plain button--icon button--round" aria-label="Account, Sam Rivera, online">
  <span class="avatar avatar--sm" aria-hidden="true">
    <img src="/examples/thumb.svg" alt="" />
    <span class="badge badge--dot badge--success badge--bottom-end" aria-hidden="true"></span>
  </span>
</button>

The Button keeps its 48px target; the Avatar inside is decorative.

Avatar Group

<ul class="avatar-group avatar-group--stacked" aria-label="Project members">
  <li><span class="avatar" role="img" aria-label="Sam Rivera">SR</span></li>
  <li><img class="avatar" src="/examples/thumb.svg" alt="Ade Okafor" /></li>
  <li><span class="avatar avatar--count" role="img" aria-label="3 more members">+3</span></li>
</ul>

• Spaced by default; --stacked overlaps each Avatar by --avatar-group-overlap (0.33 of its size) and rings it in --avatar-group-ring-color. Set the ring colour to the surface the group sits on.
• Size comes from the Avatars: --avatar-size-step: sm on the group, or a modifier on each.
• A group beside a visible list of the same names is aria-hidden="true" and needs no labels.

Do and Don’t

In Storybook

• Avatar variants and states
• Avatar Group variants and states
• Avatar tokens

See also

• Lockup: A primary line of text with a secondary one under it, such as a name and an email.
• Thumbnail: A small picture of a thing, such as album art, a product shot or a file preview.
• Badge, Status, Chip and Kbd: Small labels chosen by their job, such as a count on something, the state of something, a value someone chose or a key to press.