`<bmx-avatar-group>`

The overlapping stack of faces that says who is on something.

5 properties · 0 events · 0 methods · 2 parts

Example

max="4" over five people draws all five: a counter reading +1 takes the same room as the face it replaced and tells the reader less. Over six it draws four and a +2. The rule is shared with bmx-chip-set, because it is arithmetic rather than a property of either.

+2 is drawn and never read; what it announces is “2 more: Priya Raman, Tom Baird”. The faces themselves are decorative and the group carries the name — eight avatars each announcing themselves is eight announcements to sit through before reaching the rest of the row. The overlap is a logical margin, so the stack leans the way the reader reads and mirrors in Arabic and Hebrew with no second rule.

Show markup

<div class="row" style="gap: 2.5rem; align-items: center">
  <bmx-avatar-group
    label="Assigned to"
    max="4"
    items='[{"name":"Amara Okonkwo"},{"name":"Grace Hopper"},{"name":"Dana Scott"},{"name":"Eli Cohen"},{"name":"Priya Raman"},{"name":"Tom Baird"}]'
  ></bmx-avatar-group>

  <bmx-avatar-group
    label="Reviewers"
    items='[{"name":"Ada Lovelace"},{"name":"Katherine Johnson"}]'
  ></bmx-avatar-group>
</div>

<div class="row" style="margin-block-start: 1.5rem; gap: 2.5rem; align-items: center">
  <bmx-avatar-group label="Attending" max="4" style="--bmx-avatar-size: 2rem; --bmx-avatar-group-overlap: 0.75rem">
    <bmx-avatar name="Amara Okonkwo" decorative></bmx-avatar>
    <bmx-avatar name="Grace Hopper" decorative></bmx-avatar>
    <bmx-avatar name="Dana Scott" decorative></bmx-avatar>
    <bmx-avatar name="Eli Cohen" decorative></bmx-avatar>
    <bmx-avatar name="Priya Raman" decorative></bmx-avatar>
  </bmx-avatar-group>

  <span class="note" style="flex: 1 1 18rem">
    <code>max="4"</code> over five people draws all five: a counter reading <code>+1</code> takes the same room as the
    face it replaced and tells the reader less. Over six it draws four and a <code>+2</code>. The rule is shared with
    <code>bmx-chip-set</code>, because it is arithmetic rather than a property of either.
  </span>
</div>

<div class="row" style="margin-block-start: 1rem">
  <span class="note">
    <code>+2</code> is drawn and never read; what it announces is <em>&ldquo;2 more: Priya Raman, Tom Baird&rdquo;</em>.
    The faces themselves are <code>decorative</code> and the <em>group</em> carries the name &mdash; eight avatars each
    announcing themselves is eight announcements to sit through before reaching the rest of the row. The overlap is a
    logical margin, so the stack leans the way the reader reads and mirrors in Arabic and Hebrew with no second rule.
  </span>
</div>

<bmx-avatar-group label="Assigned to" max="4">
  <bmx-avatar name="Ada Lovelace" decorative></bmx-avatar>
  <bmx-avatar name="Grace Hopper" decorative></bmx-avatar>
</bmx-avatar-group>

`+3` IS A TRUNCATION, AND THIS ONE HAS NAMES BEHIND IT

The counter is the same kind of compromise as the badge's 99+ and the avatar's initials: it exists because the row has a width. So it gets the same treatment - the glyph is drawn aria-hidden and what is announced is "3 more: Dana, Eli, Fran", which is the information the picture was standing in for. Past five names it becomes "12 more", because a list of twelve read aloud stops being an answer and becomes an obstruction. The rule is hiddenLabel in src/core/collection.ts, and the cut-off is a judgement rather than a standard.

A LIMIT NEVER HIDES EXACTLY ONE

max="4" over five people shows all five: a counter reading +1 takes the same room as the face it replaced and tells the reader less. Shared with bmx-chip-set, because it is arithmetic rather than a property of either.

WHY THE AVATARS INSIDE ARE USUALLY `decorative`

A stack of eight faces, each announcing its own name, is eight announcements a reader has to sit through to reach the rest of the row - and the group already carries a label saying what the stack is. So the pattern this component documents is decorative on the avatars and a label here. It is not enforced: a group of two, where each face is the only thing naming the person, is the case where announcing them is right, and the component cannot see which of the two it is in.

Properties

Property	Attribute	Type	Default	Description
`decorative`	`decorative`	`boolean`	`false`	Hide the whole stack from assistive technology, when the names are listed beside it.
`items`	property only	`BmxAvatarEntry[]`	`[]`	The people, as data. Read through `src/core/markup.ts`, so an `items='[{"name":"Ada"}]'` attribute written by a server-side template is the list it looks like rather than a string the component tries to map over.
`label`	`label`	`string`	—	What the stack is: "Assigned to", "Attending", "Editors".
`max`	`max`	`number`	—	The most faces to draw before the rest become a counter. Never hides exactly one.
`moreLabel`	`more-label`	`string`	—	The counter's accessible name, when the composed one is not wanted.

Slots

Slot	Description
`(default)`	`bmx-avatar` elements.

CSS shadow parts

Part	Description
`group`	The row.
`more`	The counter.

CSS custom properties

Property	Description
`--bmx-avatar-group-more-background`	The fill of the counter.
`--bmx-avatar-group-more-color`	The text on it.
`--bmx-avatar-group-overlap`	How far each avatar sits over the one before it.
`--bmx-avatar-group-ring`	The ring that separates one avatar from the next.

<bmx-avatar-group>