Avatar Group

Quick Start

1. Add to your HTML <head>:

Code snippet omitted: it ships with the download.

2. Add before the closing </body> tag:

Code snippet omitted: it ships with the download.

3. Add the component markup:

Copy the [data-facepile] block from index.html (it is marked with <!-- Component starts here -->). It needs:

• [data-facepile] root, optionally with data-max-visible="5"
• [data-facepile-pile] > [data-facepile-row] holding one .face button per person
• .face--more[data-facepile-more] as the last child of the row (the overflow chip)
• [data-facepile-tip] for the travelling tooltip
• [data-facepile-panel] for the roster popover, with [data-facepile-list]
• a role="status" element with [data-facepile-live]

Each .face carries data-name, data-status, data-state (active, idle or call), a data-color key mapped in CSS, and an aria-label. Roster rows are built by the script from those attributes, so there is no second list to keep in sync.

What's Included

• index.html: the facepile shown at real scale in a document row, with a light/dark toggle
• assets/style.css: component CSS, the demo's ground furniture and both themes
• assets/script.js: readable GSAP core source with cleanup, keyboard model and a public API
• assets/script.min.js: minified production script
• thumbnail.html: build-only capture state

Using It With Your Own Design

What the effect needs from your markup: the data attributes listed above, and real <button> elements for every avatar and for the overflow chip. Nothing else about the surrounding page matters; the component is display: inline-flex and sits wherever you put it.

What is only the demo's styling: everything named .stage-* (the ground, the document row it sits in, the Share button), the .showcase-toolbar strip and the Google Font link. That is demo furniture, not part of what you bought — delete it. The toolbar's Join, Leave and Overflow buttons are there to drive the public API, nothing more.

CSS the effect depends on: do not put a CSS transform on .face, on [data-facepile-row], on [data-facepile-tip] or on .roster — GSAP owns those, and a CSS transform underneath one is read as a pixel offset it never returns from. Under .has-js the row becomes a positioned stage and each .face is an absolute item; without JS they fall back to a flex row with negative margins, which is why the pile still looks right with JavaScript off. Keep --face-size, --step-rest and --step-open defined on the root: the script reads them at use time and re-reads them after a theme switch or a resize.

Themes

Two themes, one design at two token values: light (the default) and dark. Set the attribute on the component's owning root in your own page, or on <body> in the demo:

Code snippet omitted: it ships with the download.

The demo-only toggle and the ?variant=dark URL parameter change that attribute; neither is part of the component. The JavaScript never reads the theme name — it only reads the three geometry properties, at use time.

Everything is a custom property set in both body[data-variant="light"] and body[data-variant="dark"] in assets/style.css. To wear your own brand, re-value this one list in both blocks:

• Ground and surfaces: --ground, --ground-2, --raised, --hover
• Text: --ink, --ink-2, --ink-3
• Lines, radii, elevation: --line, --line-strong, --radius, --radius-sm, --shadow
• Accent: --accent, --accent-ink (the focus ring, the join ping, the row's primary action)
• The pile: --face-size, --step-rest, --step-open, --face-font, --face-ring, --face-shadow, --face-radius, --face-fg, --more-bg, --more-fg, --ping-color
• Avatar discs: --face-a … --face-h, mapped from each face's data-color. Solid colours, dark enough for the white initials on them
• Presence: --dot-active, --dot-idle, --dot-call, --dot-ring
• Tooltip: --tip-bg, --tip-fg, --tip-muted, --tip-radius, --tip-border, --tip-shadow
• Roster popover: --panel-bg, --panel-border, --panel-radius, --panel-shadow, --panel-row-hover, --panel-rule

A chunkier look wants a bigger --step-open as well as a bigger --face-size; the script re-measures both after the theme switch dispatches a resize.

How It Works

One geometry function. Rest, parted and hovered positions all come from a single pass over the current items, so nothing is left holding a stale transform after a hover, a join or a resize. The row reserves the width of its parted state, so parting the stack never nudges the toolbar around it.

The tooltip is one node. It is measured against the new name, then tweened to a new x and a new width while its content crossfades — one object travelling, rather than two labels swapping.

Making room. add() re-lays the row, tweens the row's own width so surrounding chrome slides instead of jumping, and springs the new avatar's disc in with a ring ping. Past data-max-visible, the overflow chip takes the join and rolls its number instead.

Public API and events. The first instance is exposed for wiring:

Code snippet omitted: it ships with the download.

The root also dispatches facepile:focus, facepile:blur, facepile:open, facepile:close and facepile:add, each with the person in event.detail:

Code snippet omitted: it ships with the download.

Accessibility

• The row is a role="group" with a roving tabindex: one stop in the tab order, then Left/Right (or Up/Down) to move between people, Home and End for the ends.
• Enter or Space on any avatar, or on the overflow chip, opens the roster popover on that person.
• The roster is a role="dialog": focus moves into it, Tab and the arrow keys stay inside it, Escape closes it and focus returns to whatever opened it. A click outside closes it too.
• Every avatar and the overflow chip are real buttons with accessible names; presence dots are decorative and the status is in the label.
• Joins and roster selections are announced through a polite role="status" region.
• Coarse pointers get larger avatars, fully separated targets and no hover-only state — the pile is parted from the start and a tap opens the roster.
• Under prefers-reduced-motion: reduce the pile parts, the roster opens and the tooltip appears with no animation, and the ambient presence ping is off.

Requirements

• GSAP 3.12+ (the demo uses 3.15.0; core only)
• No build step or framework