Avatar Group

1"use client"
2 
3import * as React from "react"
4import { cn } from "@/lib/utils"
5 
6const SIZES = {
7  sm: { avatar: "size-6 text-[10px]", overlap: "-space-x-1.5" },
8  md: { avatar: "size-8 text-xs", overlap: "-space-x-2" },
9  lg: { avatar: "size-10 text-sm", overlap: "-space-x-2.5" },
10} as const
11 
12/** Shared shell for a disc: ring-background matches the page, so the overlap reads as a cut-out */
13const CIRCLE =
14  "relative flex shrink-0 select-none items-center justify-center overflow-hidden rounded-full bg-muted font-medium text-muted-foreground ring-2 ring-background"
15 
16/** Hovering one disc: raising z reveals it and stays, the lift is decoration (off under reduced-motion) */
17const LIFT =
18  "transition-transform duration-200 ease-out hover:z-10 hover:-translate-y-1 motion-reduce:transition-none motion-reduce:hover:translate-y-0"
19 
20export interface AvatarGroupItem {
21  src?: string
22  alt: string
23  /** Fallback letter; defaults to the first character of `alt`, uppercased. */
24  fallback?: string
25}
26 
27export interface AvatarGroupProps extends React.HTMLAttributes<HTMLDivElement> {
28  items: AvatarGroupItem[]
29  /** Anything beyond this collapses into a "+N" disc, N computed live. */
30  max?: number
31  size?: keyof typeof SIZES
32}
33 
34function AvatarItem({ item, sizeClass }: { item: AvatarGroupItem; sizeClass: string }) {
35  const [failed, setFailed] = React.useState(false)
36  const showImage = Boolean(item.src) && !failed
37 
38  return (
39    <span className={cn(CIRCLE, LIFT, sizeClass)}>
40      {showImage ? (
41        // eslint-disable-next-line @next/next/no-img-element -- registry components stay framework-agnostic, no next/image
42        <img
43          alt={item.alt}
44          className="size-full object-cover"
45          onError={() => setFailed(true)}
46          src={item.src}
47        />
48      ) : (
49        <span aria-label={item.alt} role="img">
50          {item.fallback ?? item.alt.charAt(0).toUpperCase()}
51        </span>
52      )}
53    </span>
54  )
55}
56 
57export const AvatarGroup = React.forwardRef<HTMLDivElement, AvatarGroupProps>(
58  ({ items, max = 5, size = "md", className, ...props }, ref) => {
59    const { avatar, overlap } = SIZES[size]
60    const visible = items.length > max ? items.slice(0, max) : items
61    const hidden = items.length - visible.length
62 
63    return (
64      <div className={cn("flex items-center", overlap, className)} ref={ref} {...props}>
65        {visible.map((item, i) => (
66          <AvatarItem item={item} key={`${item.alt}-${i}`} sizeClass={avatar} />
67        ))}
68// … truncated