Avatar Stack

1import * as React from "react";
2 
3import { cn } from "@/lib/utils";
4 
5interface AvatarStackProps extends React.ComponentProps<"div"> {
6  orientation?: "horizontal" | "vertical";
7  max?: number;
8  avatarSize?: number;
9  overlapRatio?: number;
10  mask?: boolean;
11}
12 
13export function AvatarStack({
14  children,
15  className,
16  orientation = "horizontal",
17  max, // Max visible avatars before "+N"
18  avatarSize, // Avatar size in pixels
19  overlapRatio = 0.2, // 20% of avatar size
20  mask = true,
21  style,
22  ...props
23}: AvatarStackProps) {
24  const items = React.Children.toArray(children);
25  const overflow = max ? Math.max(0, items.length - max) : 0;
26  const visible = items.slice(0, max);
27 
28  // Use the first child as the chip wrapper so its size, shape, and styling
29  // (Avatar from any registry, plain div, etc.) automatically apply to "+N".
30  const firstChild = visible.find(React.isValidElement);
31 
32  // `avatarSize` set: force children + chip to that pixel size; derive overlap from it.
33  // `avatarSize` omitted: children keep intrinsic size; overlap falls back to 0.5rem.
34  // Override the fallback overlap via `style={{ "--overlap": "..." }}` if needed.
35  const overlap = avatarSize != null ? `${overlapRatio * avatarSize}px` : "0.5rem";
36 
37  return (
38    <div
39      data-slot="avatar-stack"
40      data-orientation={orientation}
41      className={cn(
42        "group isolate flex items-center",
43        "data-[orientation=horizontal]:flex-row data-[orientation=horizontal]:-space-x-(--overlap)",
44        "data-[orientation=vertical]:flex-col data-[orientation=vertical]:-space-y-(--overlap)",
45        "*:shrink-0 *:object-cover *:object-center",
46        avatarSize != null && "*:size-(--avatar-size)!",
47        mask && "*:ring-2 *:ring-background",
48        className
49      )}
50      style={
51        {
52          ...style,
53          "--overlap": overlap,
54          ...(avatarSize != null && { "--avatar-size": `${avatarSize}px` }),
55        } as React.CSSProperties
56      }
57      {...props}
58    >
59      {visible}
60      {overflow > 0 &&
61        firstChild &&
62        React.cloneElement(
63          firstChild as React.ReactElement<Record<string, unknown>>,
64          { key: "overflow", "data-slot": "avatar-stack-overflow" },
65          <span className="flex size-full items-center justify-center rounded-[inherit] bg-muted text-xs font-medium text-muted-foreground">
66            +{overflow}
67          </span>
68        )}
69    </div>
70  );
71}