Avatar group
An avatar group shows a few overlapping avatars and a "+N" button that lists the rest.
<tk-avatar-group label="4 collaborators"> <tk-avatar shape="circle" name="Mira Petrova"></tk-avatar> <tk-avatar shape="circle" name="Ola Nordmann"></tk-avatar> <tk-avatar shape="circle" name="Sam Lee"></tk-avatar> <tk-avatar name="Acme Corp"></tk-avatar> </tk-avatar-group>
Anatomy
| Part | What it is |
|---|---|
tk-avatar-group |
the row; a named group when label is set |
| default slot | the tk-avatar faces; the first one is on top |
| ring | a 2px ring around each face, in the page color |
| "+N" button | appears when the faces exceed max; opens a |
overflow slot |
optional content for the popover, instead of the name list |
Overflow
<tk-avatar-group max="5" label="8 collaborators"> <tk-avatar shape="circle" name="Mira Petrova" color="blue"></tk-avatar> <tk-avatar shape="circle" name="Ola Nordmann" color="pink"></tk-avatar> <tk-avatar shape="circle" name="Sam Lee" color="green"></tk-avatar> <tk-avatar shape="circle" name="Jo Kim" color="indigo"></tk-avatar> <tk-avatar shape="circle" name="Al Roy" color="teal"></tk-avatar> <tk-avatar shape="circle" name="Bea Fox" color="orange"></tk-avatar> <tk-avatar shape="circle" name="Cy Ng" color="purple"></tk-avatar> </tk-avatar-group>
maxcounts every tile, including "+N". With more faces thanmax, the group showsmax − 1faces and a "+N" tile, so "+N" always hides at least two.- N is the number of hidden faces. To show a larger total, such as "200 members", write it as text next to the group.
- The "+N" button opens a popover that lists the hidden faces with their names. The
rows aren't commands. For rows that link somewhere, put your own content in the
overflowslot.
Sizes
<tk-avatar-group size="24" label="3 reviewers"> <tk-avatar shape="circle" name="Mira Petrova"></tk-avatar> <tk-avatar shape="circle" name="Ola Nordmann"></tk-avatar> <tk-avatar shape="circle" name="Sam Lee"></tk-avatar> </tk-avatar-group>
size takes the size on a face inside a group is ignored. The overlap is
about a third of the size.
Shapes
Each face keeps its own shape, so people (circles) and bots or organizations (squares) can
share a row. The group has no shape. "+N" is always a rounded square. See the
Badges on faces are hidden inside a group.
When to use
- Use a group for a quick look at who is here, where space is tight: a "Shared with" bar, a toolbar, a card.
- Use a list for a full member list, one avatar per row, with a count in the header.
- Use an
Avatar for one person or entity. - "+N" means more people. For an "add person" action, add an
Icon button with a "+" after the group.
Do / Don't
| ✅ Do | ❌ Don't |
|---|---|
| Use a group as a quick preview of who is here | Use it as a full member list |
Set label when the group stands alone |
Leave a standalone group silent |
| Mix circles and squares when each is true | Make a bot a circle to match the row |
| Write a larger total as text next to the group | Expect "+N" to show more than the hidden faces |
Put clickable rows in the overflow slot |
Wrap faces in links inside the group; it takes only tk-avatar children |
Related
Avatar : the face the group stacks.Popover : the surface "+N" opens.Badge : status on a single avatar.
API
Attributes
| Attribute | Type | Default | What it does |
|---|---|---|---|
size |
20 | 24 | 32 | 40 | 48 | 64 |
32 |
the size of every face and "+N" |
max |
number | 5 |
tiles shown, including "+N" |
label |
string | names the group for screen readers |
Slots
| Slot | Content |
|---|---|
| default | tk-avatar faces, first on top |
overflow |
your rows for the "+N" popover, replacing the name list |
Events
None.
CSS
| Custom property | Default | What it does |
|---|---|---|
--tk-avatar-group-overlap |
by size | how far faces overlap |
--tk-avatar-group-ring-color |
surface/default |
the ring color; set it on a surface other than surface/default |
Tokens
| Element | Tokens |
|---|---|
| ring | surface/default |
| "+N" tile | surface/sunken + text/secondary, font-weight-medium |
| "+N" corner | radius-4, radius-8, radius-12 by size |
| "+N" focus ring | border/accent/focus |
| faces | the |
| overflow surface | the |
Accessibility
Built in:
- The faces are hidden from screen readers. With
label, the group is a named group. - "+N" is a button in the Tab order, named "Show N more", with a focus ring. Its popover lists the hidden names.
Your part:
- Set
labelwhen the group stands alone: "5 collaborators". - Leave
labelunset next to visible text such as "Shared with", so it isn't read twice. - Don't set
labelon faces inside a group. - The "+N" button's name is in English and can't be changed.
| Key | Action |
|---|---|
Tab |
moves focus to "+N" |
Enter / Space |
opens the popover |
Esc |
closes it |