Skip to content
VenusUI
Get started

Avatar Stack

Overlapping avatars with a +N counter that spread apart on hover.

Preview

Installation

npx shadcn@latest add @venusui/avatar-stack

Run this in a project set up with shadcn. If you haven’t set it up yet, run npx shadcn@latest init first.

Files added to your project

Paths use the default shadcn aliases. The CLI follows the aliases in your components.json.

  • @/components/ui/avatar-stack.tsx

Usage

The code behind the preview above.

avatar-stack-demo.tsx

import { AvatarStack } from "@/components/ui/avatar-stack"

const people = ["Ananya Iyer", "Marcus Webb", "Lucía Moreno", "Kenji Sato", "Fatima Noor", "Jonas Berg", "Chloé Martin", "Ravi Kapoor"].map((name) => ({ name }))

export default function AvatarStackDemo() {
  return (
    <div className="flex items-center gap-3">
      <AvatarStack people={people} max={5} />
      <p className="text-sm text-muted-foreground">8 people are viewing this page</p>
    </div>
  )
}

API reference

PropTypeDefaultDescription
people{ name: string; src?: string }[]—People to show. Without src, initials are used. Required.
maxnumber5Avatars shown before “+N”.
sizenumber36Avatar size in pixels.

All <div> props except children.

Requirements

  • Tailwind CSS v4. Works in Server Components.

Customization

  • Uses a plain <img> so it works anywhere; swap in next/image in Next.js if you prefer.
  • The ring between avatars uses the background color, so it adapts to your theme.

Accessibility

  • The group is one labelled image naming everyone (“A, B, C and 3 more”), instead of many unlabeled pictures.

Troubleshooting

Next.js warns about <img>.
It’s a lint warning from @next/next/no-img-element. Switch to next/image, or keep the plain image.
Unknown registry "@venusui"
Your shadcn CLI couldn’t find the namespace in the shadcn registry index. Use the latest CLI (npx shadcn@latest), install by URL, or register it with its address: npx shadcn@latest registry add @venusui=https://venusui.com/r/{name}.json.
No components.json found
Run npx shadcn@latest init in your project first.
Loading preview

Analog Clock

Data display

A station clock whose needle waits at twelve; drag the minute hand to set it by hand.

Loading preview

Bookshelf

Interactive

Books on a wooden shelf whose spines lift on hover and pull out when selected, with a matching cover.

Loading preview

Chat Thread

Data display

A messaging conversation that plays out with typing indicators; viewers can send replies too.