Avatar
A small square or circle standing for a person or a thing: an image, or the initials when there is no image. Four sizes, an optional ring, a status dot and groups that overlap with a count for the rest. It carries no identity of its own — the accessible name comes from the alt of the image or from an aria-label on the container. No JavaScript.
<div class="iv-u-flex iv-u-flex-wrap iv-u-gap-6 iv-u-items-center">
<span class="iv-avatar iv-avatar--sm" role="img" aria-label="Ada Márquez"><span aria-hidden="true">AM</span></span>
<span class="iv-avatar" role="img" aria-label="Ada Márquez"><span aria-hidden="true">AM</span></span>
<span class="iv-avatar iv-avatar--lg" role="img" aria-label="Bruno Oteiza"><span aria-hidden="true">BO</span></span>
<span class="iv-avatar iv-avatar--xl" role="img" aria-label="Chen Wei"><span aria-hidden="true">CW</span></span>
</div>
<div class="iv-u-flex iv-u-flex-wrap iv-u-gap-6 iv-u-items-center iv-u-mt-8">
<span class="iv-avatar iv-avatar--lg iv-avatar--ring" role="img" aria-label="Ada Márquez"><span aria-hidden="true">AM</span></span>
<span class="iv-avatar iv-avatar--lg iv-avatar--square" role="img" aria-label="Bruno Oteiza"><span aria-hidden="true">BO</span></span>
<span class="iv-avatar iv-avatar--lg">
<img class="iv-avatar__img" src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 40 40'%3E%3Crect width='40' height='40' fill='%231D4FC4'/%3E%3Cpath d='M20 32c0-9 5-15 13-17-1 10-6 15-13 17z' fill='%2373DFFF'/%3E%3Cpath d='M20 32c0-6-3-10-10-11 1 7 4 10 10 11z' fill='%23EAF4FF' opacity='.85'/%3E%3C/svg%3E" alt="Drawing of a plant, used here instead of a portrait" width="56" height="56">
</span>
<span class="iv-avatar iv-avatar--lg" role="img" aria-label="Ada Márquez">
<span aria-hidden="true">AM</span>
<span class="iv-avatar__status" data-iv-tone="success"><span class="iv-u-sr-only">Online</span></span>
</span>
<span class="iv-avatar iv-avatar--lg" role="img" aria-label="Bruno Oteiza">
<span aria-hidden="true">BO</span>
<span class="iv-avatar__status" data-iv-tone="warning"><span class="iv-u-sr-only">Away</span></span>
</span>
<span class="iv-avatar iv-avatar--lg" role="img" aria-label="Chen Wei">
<span aria-hidden="true">CW</span>
<span class="iv-avatar__status" data-iv-tone="muted"><span class="iv-u-sr-only">Offline</span></span>
</span>
</div>
<p class="iv-u-text-sm iv-u-text-muted iv-u-mt-6" style="max-width: 40rem">The names and initials are invented: this package ships no photographs of people. The single image above is an inline SVG drawing of a plant, not a portrait. The status dot repeats its meaning in text for screen readers, so the colour is never alone.</p>Groups
iv-avatar-group lays faces in a row, each overlapping the one before by just under a fifth of its size, with the first on top. The last item can be iv-avatar-group__more: a muted face carrying the count of everyone not shown, with that count in its label. Tune the overlap in one line with --iv-avatar-overlap on the group.
<div class="iv-avatar-group">
<span class="iv-avatar" role="img" aria-label="Ada Márquez"><span aria-hidden="true">AM</span></span>
<span class="iv-avatar" role="img" aria-label="Bruno Oteiza"><span aria-hidden="true">BO</span></span>
<span class="iv-avatar" role="img" aria-label="Chen Wei"><span aria-hidden="true">CW</span></span>
<span class="iv-avatar" role="img" aria-label="Dario Ferri"><span aria-hidden="true">DF</span></span>
<span class="iv-avatar iv-avatar-group__more" role="img" aria-label="3 more people"><span aria-hidden="true">+3</span></span>
</div>
<div class="iv-avatar-group iv-u-mt-8" style="--iv-avatar-overlap: -0.35rem">
<span class="iv-avatar iv-avatar--lg" role="img" aria-label="Ada Márquez"><span aria-hidden="true">AM</span></span>
<span class="iv-avatar iv-avatar--lg" role="img" aria-label="Bruno Oteiza"><span aria-hidden="true">BO</span></span>
<span class="iv-avatar iv-avatar--lg" role="img" aria-label="Chen Wei"><span aria-hidden="true">CW</span></span>
<span class="iv-avatar iv-avatar--lg iv-avatar-group__more" role="img" aria-label="12 more people"><span aria-hidden="true">+12</span></span>
</div>
<div class="iv-avatar-group iv-u-mt-8">
<span class="iv-avatar iv-avatar--sm iv-avatar--square" role="img" aria-label="Ada Márquez"><span aria-hidden="true">AM</span></span>
<span class="iv-avatar iv-avatar--sm iv-avatar--square" role="img" aria-label="Bruno Oteiza"><span aria-hidden="true">BO</span></span>
<span class="iv-avatar iv-avatar--sm iv-avatar--square" role="img" aria-label="Chen Wei"><span aria-hidden="true">CW</span></span>
</div>
<p class="iv-u-text-sm iv-u-text-muted iv-u-mt-6" style="max-width: 40rem">Invented names again. Each face is an image with its own label and the overflow count says how many people are not shown. The overlap is an eighth of the face at every size and the initials sit against the visible edge, so the ones behind stay readable; <code>--iv-avatar-overlap</code> retunes it in one line — the middle row above is set to a looser <code>-0.35rem</code>.</p>.iv-root {
--iv-avatar-overlap: -0.35rem;
}Anatomy
| Class | Role |
|---|---|
iv-avatar | The face: 2.5rem, full radius, brand-tinted ground for initials. |
iv-avatar__img | The image inside it, cropped with object-fit: cover. Give it width and height. |
iv-avatar--sm --lg --xl | 1.75rem, 3.5rem and 5rem, all through --iv-avatar-size. |
iv-avatar--square | Rounded square instead of a circle. |
iv-avatar--ring | A brand ring around the face. |
iv-avatar__status | Dot at the bottom end corner; data-iv-tone takes success, warning, danger and muted. |
iv-avatar-group, iv-avatar-group__more | The row and its overflow count. |
Initials are the default rendering: put them in a <span aria-hidden="true"> inside an avatar that carries role="img" and the full name in aria-label, so a screen reader reads the person and not two letters. There is no separate modifier class for them.
Tokens and locals
| Local | Default | What it moves |
|---|---|---|
--iv-avatar-size | 2.5rem | Diameter of the face; the size modifiers only set this. |
--iv-avatar-radius | var(--iv-radius-full) | Corner radius; --square switches it to md. |
--iv-avatar-ring | transparent | Colour of the ring; --ring sets it to the brand. |
--iv-avatar-overlap | calc(var(--iv-avatar-size) * -0.18) | How much each face in a group covers the previous one. |
The default overlap is a calculation rather than a fixed length so a row of small faces and a row of large ones keep the same rhythm and the initials behind stay legible. Set it on the group, not on a face.
Accessibility and keyboard
An avatar is not interactive, so there is nothing to focus unless you wrap it in a link or a button — and then the link needs its own accessible name, not just the picture. Decide once whether the avatar is content or decoration: with a name it is an image of a person, and repeating that name in the text beside it gives a screen reader the same thing twice; in that case make the avatar alt="" or aria-hidden and let the text carry the identity. The status dot must repeat its meaning in words, as the fixture does with a hidden "Online"; colour alone says nothing. The overflow count says how many people are not shown, so the row is not a lie of omission.
Without JavaScript
There is no JavaScript. A broken image falls back to its alt text centred in the face rather than a torn icon.
Common mistakes
- Initials with no name: two letters read aloud are noise.
alt="avatar"oralt="profile picture". Either the name, or empty.- A status dot that only exists in colour.
- A group of twenty faces without a count. Show four or five and say how many are left.
- Photographs of people invented for a demo. The fixtures here use invented initials and a drawing, and say so.
Class index
Parts and modifiers of this family that the examples above do not show. The full list per stylesheet lives in the reference.
| Class | What it does |
|---|---|
iv-avatar--lg | 3.5rem avatar. |
iv-avatar--xl | 5rem avatar, for a profile header. |