Avatar Group

How the Avatar Group works with a keyboard and assistive tech, and where it stands against WCAG 2.2 AA.

FreeReact and Vue

AAWCAG 2.2 target

2keyboard interactions

The Avatar Group is a role="group" named with the total, such as "12 people", holding one labelled Avatar per visible face and a +N disc. Each face is announced by name and the disc as "N more", so the overlap that saves space on screen costs nothing to a screen reader.

Keyboard#

Tab

Passes over the group: nothing in it is focusable. If the +N disc opens the full list, make it a button and it takes focus.

Enter

Only when the +N disc is a button: opens the list of everyone.

Semantics#

role="group"

Groups the faces so they are read as one set.

Always

aria-label

"{total} people" by default. Pass ariaLabel with the noun that fits, such as "8 members" or "3 assignees".

Always

role="img" + aria-label

Each face is named, as a single Avatar is.

Each avatar

role="img" aria-label="N more"

Read as "5 more", not "plus 5".

+N disc

<button aria-expanded>

Not built in. Wrap the disc in a button and set aria-expanded to match the list.

If +N opens a list

Colour contrast#

Every variant and state has to meet WCAG 2.2 Level AA. Measure the colours as they land on screen: a translucent hover or press wash over whatever sits behind it.

4.5:1

+N count · More disc

Satoshi Bold in #2a2a2a on the #fcfcfc disc measures 13.99:1. At the smaller sizes (10 to 16px) it is normal text, so 4.5:1 is the bar.

WCAG 1.4.3 Contrast (Minimum) ↗

See Avatars

Avatars · Each face

Initials and badges inside the group follow the single Avatar's figures. The overlap hides part of each disc, so do not rely on a badge on a tucked-under face.

WCAG 1.4.3 Contrast (Minimum) ↗WCAG 1.4.11 Non-text Contrast ↗

Motion#

The group does not animate.

Checklist#

Name the group with what the people are: "8 members", "3 reviewers". The default "N people" is a fallback.

Pass total when the list is longer than the faces you send, so the +N and the group's label agree.

If the +N opens a list, it has to be a real button with aria-expanded and a 24px target; the component does not do this for you.

On a card that is itself a link, the group's names are read inside the link's name. Keep it short or hide the group there.