PixelAvatarGroup

Clusters PixelAvatar children into an overlapping row with a tone-aware "+N" overflow tile when the count exceeds max.

  • Overlapping layout with surface-aware ring isolation against the page background
  • Configurable max — extras collapse into a single "+N more" tile (tone-aware)
  • Five sizes (xs/sm/md/lg/xl) with proportional negative-margin overlap
  • Surface-aware radius (pixel → squared 3px / linear → fully rounded)
  • role="group" only when an accessible name is provided (aria-label / aria-labelledby)
Status
stable
Category
data
Since
v1.9.0

API

import { PixelAvatarGroup } from '@pxlkit/ui-kit';
PropTypeDefaultDescription
maxnumber5Most places the row shows; beyond it, the last place becomes a "+N" tile.
size'xs' | 'sm' | 'md' | 'lg' | 'xl''md'Slot size — match it to the avatars inside.
tone'neutral' | 'green' | 'cyan' | 'gold' | 'red' | 'purple' | 'pink''neutral'Tone of the "+N" tile.
surface'pixel' | 'linear'—Surface override; defaults to the nearest provider.
aria-labelstring—Accessible name for the avatar landmark. Without one, role=group is dropped.
aria-labelledbystring—Id of the element that names the group, in place of aria-label.
children (required)React.ReactNode—The avatars.

Also takes the native attributes and event handlers of <div> (HTMLAttributes<HTMLDivElement>).

ref points to <div>.

Accessibility

WCAG target: 2.1 AA

  • group

Provide aria-label or aria-labelledby summarizing the count (e.g. "5 team members"); without one, role=group is dropped so the cluster is treated as presentational. The "+N" overflow tile hides its visible "+N" from assistive tech and announces "N more users" through screen-reader-only text.

Usage

import { PixelAvatarGroup, PixelAvatar } from '@pxlkit/ui-kit';

export function Default() {
  return (
    <PixelAvatarGroup aria-label="3 team members">
      <PixelAvatar name="Joangel De La Rosa" />
      <PixelAvatar name="Ana Lopez" />
      <PixelAvatar name="Carlos Diaz" />
    </PixelAvatarGroup>
  );
}

Examples

Default

import { PixelAvatarGroup, PixelAvatar } from '@pxlkit/ui-kit';

export function Default() {
  return (
    <PixelAvatarGroup aria-label="3 team members">
      <PixelAvatar name="Joangel De La Rosa" />
      <PixelAvatar name="Ana Lopez" />
      <PixelAvatar name="Carlos Diaz" />
    </PixelAvatarGroup>
  );
}

With Overflow

import { PixelAvatarGroup, PixelAvatar } from '@pxlkit/ui-kit';

export function WithOverflow() {
  return (
    <PixelAvatarGroup aria-label="6 team members" max={4}>
      <PixelAvatar name="Joangel De La Rosa" />
      <PixelAvatar name="Ana Lopez" />
      <PixelAvatar name="Carlos Diaz" />
      <PixelAvatar name="Diana Perez" />
      <PixelAvatar name="Eduardo Ruiz" />
      <PixelAvatar name="Fabiola Garcia" />
    </PixelAvatarGroup>
  );
}

Sizes

import { PixelAvatarGroup, PixelAvatar } from '@pxlkit/ui-kit';

export function Sizes() {
  return (
    <div className="flex flex-col gap-3">
      <PixelAvatarGroup aria-label="Extra small group" size="xs">
        <PixelAvatar name="Ana Lopez" size="xs" />
        <PixelAvatar name="Bob Brown" size="xs" />
        <PixelAvatar name="Carol Chen" size="xs" />
      </PixelAvatarGroup>
      <PixelAvatarGroup aria-label="Medium group" size="md">
        <PixelAvatar name="Ana Lopez" size="md" />
        <PixelAvatar name="Bob Brown" size="md" />
        <PixelAvatar name="Carol Chen" size="md" />
      </PixelAvatarGroup>
      <PixelAvatarGroup aria-label="Extra large group" size="xl">
        <PixelAvatar name="Ana Lopez" size="xl" />
        <PixelAvatar name="Bob Brown" size="xl" />
        <PixelAvatar name="Carol Chen" size="xl" />
      </PixelAvatarGroup>
    </div>
  );
}

Tones

import { PixelAvatarGroup, PixelAvatar } from '@pxlkit/ui-kit';

export function Tones() {
  return (
    <div className="flex flex-col gap-3">
      <PixelAvatarGroup aria-label="Cyan team" tone="cyan" max={3}>
        <PixelAvatar name="Ana Lopez" tone="cyan" />
        <PixelAvatar name="Bob Brown" tone="cyan" />
        <PixelAvatar name="Carol Chen" tone="cyan" />
        <PixelAvatar name="Dave Diaz" tone="cyan" />
      </PixelAvatarGroup>
      <PixelAvatarGroup aria-label="Gold team" tone="gold" max={3}>
        <PixelAvatar name="Ana Lopez" tone="gold" />
        <PixelAvatar name="Bob Brown" tone="gold" />
        <PixelAvatar name="Carol Chen" tone="gold" />
        <PixelAvatar name="Dave Diaz" tone="gold" />
      </PixelAvatarGroup>
      <PixelAvatarGroup aria-label="Purple team" tone="purple" max={3}>
        <PixelAvatar name="Ana Lopez" tone="purple" />
        <PixelAvatar name="Bob Brown" tone="purple" />
        <PixelAvatar name="Carol Chen" tone="purple" />
        <PixelAvatar name="Dave Diaz" tone="purple" />
      </PixelAvatarGroup>
    </div>
  );
}

Surfaces

import { PixelAvatarGroup, PixelAvatar } from '@pxlkit/ui-kit';

export function Surfaces() {
  return (
    <div className="flex flex-col gap-3">
      <PixelAvatarGroup aria-label="Pixel surface group" surface="pixel">
        <PixelAvatar name="Ana Lopez" surface="pixel" />
        <PixelAvatar name="Bob Brown" surface="pixel" />
        <PixelAvatar name="Carol Chen" surface="pixel" />
      </PixelAvatarGroup>
      <PixelAvatarGroup aria-label="Linear surface group" surface="linear">
        <PixelAvatar name="Ana Lopez" surface="linear" />
        <PixelAvatar name="Bob Brown" surface="linear" />
        <PixelAvatar name="Carol Chen" surface="linear" />
      </PixelAvatarGroup>
    </div>
  );
}

Related