Skip to content

Avatar

C-04 · Components · Actions

All elements · Avatar on the Components page

Last checked 2026-10-22 · Awaiting approval · Accessibility tests

Copies the bun run a11y:approve command for Avatar.

Avatar

C-04WCAG 2.2 AA · Passed #397
Axis Values
data-size 3xs · 2xs · xs · sm · md (default) · lg · xl · 2xl
data-color · data-shape primary (default) · info · success · … / circle · square
.qf-avatar__img · .qf-icon · text src / icon / initials
.qf-avatar__status[data-status] online · busy · away · offline
.qf-avatar-group · [data-overflow] stack with +N
Initials, icon, image, status, group
jd ak mr jd bs aw
jd ak mr +4

Avatar: presence

C-04 Office

Collaborators carry a ring in their presence color (--qf-presence-1…8) and a badge for viewing or editing; the name is always shown beside the avatar or in its tooltip, so hue never identifies a user on its own.

Axis / element Values
data-presence 1 … 8
.qf-avatar__badge viewing (eye) · editing (pencil)
Group
JDMRPSTO

Guidance

When to use

  • Use an avatar to show who owns, created or is assigned to a record.
  • Use an icon avatar for a non-person entity, such as a building for an organization.
  • Use an avatar group with a data-overflow +N avatar to show several people in little space.
  • Use data-presence with a viewing or editing badge to show collaborators in the office editors.

When to consider something else

  • If the person is a removable value in a field, use a chip with a leading avatar. See Chip.
  • If the user needs details about the person, open a popover from a button that contains the avatar. See Popover.
  • If you list many people with details, use a list with avatars in the leading slot. See List.

Usability

Do
  • Show the person's name next to the avatar wherever space allows.
  • Use initials when there is no photo, and keep one color per person across the app.
  • Give the +N overflow avatar a way to see the hidden people, such as a popover list.
  • In the editors, keep the presence color and the name together; the badge says viewing or editing.
Don’t
  • Don't use the avatar as the only way to identify a person.
  • Don't use the status dot color alone to show online, busy or away.
  • Don't use 3xs or 2xs avatars as click targets.

Accessibility

Keyboard

No keyboard interaction of its own.

Roles and names

  • An avatar is not interactive; it has no keyboard behavior. If it opens something, wrap it in a button with a name.
  • When the name is shown beside it, hide the avatar from assistive tech or give the image alt="", as the specimen does.
  • When the avatar stands alone, give it role="img" and an aria-label with the full name, not the initials.
  • The presence specimen uses role="img" with aria-label="Jane Doe, editing", so the badge state is in the name.
  • The status dot (.qf-avatar__status) has no text; put the status in the accessible name, such as "Jane Doe, busy".

Focus

  • The avatar takes no focus. The +N overflow, if it opens a list, must be a button with a name such as "4 more people".

Other requirements

  • The keyboard list is empty because the avatar is purely visual; any keyboard behavior belongs to the control that contains it.
  • Presence ring colors and status dots must not carry meaning alone (1.4.1); the name and badge or text must say it.
  • title on a presence avatar is not reachable by keyboard; put the name in the accessible name and show it on focus of the containing control (1.4.13).
  • Initials text must reach 4.5:1 on the avatar color (1.4.3).

Test your implementation too. This guidance covers the element as specified here. How a screen composes it (labels, order, announcements) still needs its own keyboard and screen reader check.

Accessibility tests

WCAG 2.2 AA · Passed

Passed the gate (run 358b316 on 2026-10-22): no finding in any theme. Awaiting a person’s approval of the checklist below.

Avatar test checklist
Area Automated A person checks
General Passed Color is never the only cue, text alternatives say the same thing as the graphic, and the element reads the same in the light and the dark theme.
Zoom Passed At 200% zoom, at 320 CSS pixels wide and with the WCAG text-spacing overrides, nothing is lost, clipped or overlapping.
Keyboard Passed Every row of the Keyboard table works, focus is always visible and never trapped, and the tab order follows the reading order.
Screen reader Passed With NVDA or JAWS on Windows and VoiceOver on macOS, names, roles and states are announced as Roles and names says, and changes are announced once. (5 items)

Approving. When the checklist passes on the checked run, record it with bun run a11y:approve -- avatar --by "Your name" and commit a11y/approvals.json with the rebuilt pages. All test status

Package

Consumers link one stylesheet, css/classic/index.css, which includes every element. The files below are where this element is defined.

Avatar package
Source css/classic/components/actions.css
css/classic/components/collab.css
Specimens also use Box · Card · Chip · Icon · Table · Text · Toolbar
Sprites sprites/icons.svg · sprites/office-icons.svg
React Not yet available: the React binding has not started.

Latest updates

No recorded changes yet.

All release notes