Avatar Cluster React Component

LIVE PREVIEWInteract with the component

Just React. No extra dependencies.

Copy the component and its CSS module into your project.

CSS Modules

Usage

Matches your current playground settings.

import AvatarCluster from "./AvatarCluster";

export default function Example() {
  return (
    <AvatarCluster
      items={[
        {
          "id": "al",
          "name": "Alex Lane",
          "description": "Designer",
          "initials": "AL",
          "color": "#aa8d77"
        },
        {
          "id": "mk",
          "name": "Maya Kim",
          "description": "Creative developer",
          "initials": "MK",
          "color": "#82759e"
        },
        {
          "id": "jr",
          "name": "Jules Reed",
          "description": "Art director",
          "initials": "JR",
          "color": "#688882"
        },
        {
          "id": "sw",
          "name": "Sam West",
          "description": "Motion designer",
          "initials": "SW",
          "color": "#b8787d"
        }
      ]}
      size={66}
      overlap={18}
      borderColor={"#18151c"}
      accentColor={"#d5bee8"}
    />
  );
}

Using Avatar Cluster

Use Avatar Cluster for contributors, collaborators, or a small team. Pass each person's display information through items.

Adjust size and overlap together to keep neighbouring portraits recognisable. Connect onSelect to the profile or action you want to open.

Props

Name	Type	Required	Default	Description
items	object[]	No	[]	Array of { id, name, description?, image?, initials?, color? }. Without an image, initials are derived from the name.
onSelect	function	No	undefined	Called with (item, index) when an avatar is activated.
activeIndex	number \| null	No	undefined	Optional controlled open name-card index. Null hides all name cards.
onActiveChange	function	No	undefined	Called with the hovered or focused index, or null on leaving.
size	number	No	58	Avatar diameter in pixels.
overlap	number	No	16	Overlap between neighboring avatars in pixels, capped to 65% of size.
borderColor	string	No	"#18151c"	Avatar border colour; match it to your container background.
accentColor	string	No	"#d5bee8"	Keyboard focus-ring colour.
className	string	No	""	Additional CSS classes, merged with the component styles.
style	CSSProperties	No	undefined	Inline styles for caller-defined sizing and visual overrides.