92 / Blocks

Avatar Stack

Overlapping faces with a count for the rest, and the names underneath as a real list.

Ada Lovelace
Grace Hopper
Alan Turing
Katherine Johnson

Point at the group and it fans out.

"use client"

import { AvatarStack } from "mischief-ui/avatar-stack"

const people = [
  { id: "1", name: "Ada Lovelace" },
  { id: "2", name: "Grace Hopper" },
  { id: "3", name: "Alan Turing" },
  { id: "4", name: "Katherine Johnson" },
  { id: "5", name: "Radia Perlman" },
  { id: "6", name: "Barbara Liskov" },
]

export function AvatarStackDemo() {
  return (
    <div className="grid justify-items-center gap-3">
      <AvatarStack people={people} label="On this document" />
      <p className="text-muted-foreground text-xs">
        Point at the group and it fans out.
      </p>
    </div>
  )
}

Installation

Copy the source into your project, or keep it behind a package.

npx shadcn@latest add Tinkerers-Labs/mischief-ui/avatar-stack

import { AvatarStack } from "mischief-ui/avatar-stack"

Or paste it in yourself. The source imports the shared cn helper from @/lib/utils, so point that at your own copy.

registry/default/avatar-stack/avatar-stack.tsx

1"use client"2 3/* eslint-disable @next/next/no-img-element -- This must work outside Next.js. */4 5import * as React from "react"6import { cn } from "@/lib/utils"7 8export type Person = {9  id?: string10  name: string11  src?: string12}13 14export type AvatarStackProps = Omit<

Usage

export function Editors({ people }) {
  return <AvatarStack people={people} max={4} label="Editing now" />
}

Faces on top of a list

The stack is a named list and each face is an item in it, so the group is read as the people it contains rather than as a row of pictures. Someone without a picture gets their initials drawn, with their full name still carried underneath, because initials read aloud are not a name.

The overflow count says how many more there are in words as well as showing a number, so it is announced as a quantity of people rather than as a plus sign and a digit.

API

peoplePerson[]Everyone, not only the ones shown.

maxnumberHow many faces before the rest become a count. Defaults to 4.

sizenumberPixels across. Defaults to 32.

spreadbooleanFans the stack out under the pointer. On by default.

labelstringNames the group. Defaults to "People".

Person

namestringUsed as the picture's alt text, or as initials.

srcstringOptional picture. Without one, initials are drawn.

idstringOptional key.

Accessibility

A named list whose items carry full names, whether shown as a picture or as initials. The overflow is announced as a number of further people. Under reduced motion the stack does not fan out, and nothing about the group depends on it having done so.