Are the ai2 Avatar stacks free?

Yes. The whole styled layer is free and MIT licensed, like the component core.

Do they respect reduced motion?

Yes. Under prefers-reduced-motion, there is no motion to reduce.

Can I change the size?

Yes. Every variation takes a size prop of sm, md, lg or xl, aligned to the base Button height scale.

Avatar stacks

Five group layouts: an overlapping stack, a stack with a plus-N, a spaced row, a fanned stack and a grid. Each is sized and token-driven, and takes a count.

AvatarsStack

Installation

The styled layer is free and installs like any other ai2 component.

Run the following command

npx shadcn@latest add @ai2/avatars-stack

Dependencies, the @ai2/tokens theme and the component file are installed together.

Copy the source

components/ui/avatars-stack.tsx

"use client"

import type * as React from "react"

import { cn } from "@/lib/utils"

/* Stack avatar family: 5 decorative layouts showing a GROUP of avatars together. Initials-based (no external image) - a consumer can put an <img> in place of the initials for each child. `count` says how many avatars are drawn and `initials` gives an optional array of initials (otherwise A/B/C... is generated deterministically). Colour comes ONLY from tokens, size = each child's box scale (box[size]). Static - no motion. */

export type StyledSize = "sm" | "md" | "lg" | "xl"

const box: Record<StyledSize, string> = {
  sm: "size-8 text-xs",
  md: "size-10 text-sm",
  lg: "size-12 text-base",
  xl: "size-16 text-lg",
}

const face =
  "flex size-full items-center justify-center rounded-full bg-secondary font-medium text-secondary-foreground select-none"

type Props = React.ComponentProps<"div"> & {
  size?: StyledSize
  count?: number
  initials?: string[]
}

/* Initials for a given index: from the supplied array, otherwise A, B, C ... (deterministic). */
function initialAt(initials: string[] | undefined, i: number) {
  if (initials && initials[i]) return initials[i]
  return String.fromCharCode(65 + (i % 26))
}

/* AvatarStack: avatars overlapping with -ml and separated by a ring. */
export function AvatarStack({ className, size = "md", count = 3, initials, ...props }: Props) {
  return (
    <div data-slot="styled-avatar" className={cn("flex items-center", className)} {...props}>
      {Array.from({ length: count }).map((_, i) => (
        <span
          key={i}
          className={cn(
            face,
            box[size],
            "shrink-0 ring-2 ring-background",
            i > 0 && "-ml-3"
          )}
        >
          {initialAt(initials, i)}
        </span>
      ))}
    </div>
  )
}

/* AvatarStackMore: ust uste binen yigin + sonda "+N" token cipi. */
export function AvatarStackMore({ className, size = "md", count = 3, initials, ...props }: Props) {
  const shown = Math.max(0, count)
  const extra = 5
  return (
    <div data-slot="styled-avatar" className={cn("flex items-center", className)} {...props}>
      {Array.from({ length: shown }).map((_, i) => (
        <span
          key={i}
          className={cn(face, box[size], "shrink-0 ring-2 ring-background", i > 0 && "-ml-3")}
        >
          {initialAt(initials, i)}
        </span>
      ))}
      <span
        className={cn(
          "flex shrink-0 items-center justify-center rounded-full bg-brand font-medium text-brand-foreground ring-2 ring-background select-none -ml-3",
          box[size]
        )}
      >
        +{extra}
      </span>
    </div>
  )
}

/* AvatarRowGap: a spaced row with no overlap. */
export function AvatarRowGap({ className, size = "md", count = 3, initials, ...props }: Props) {
  return (
    <div data-slot="styled-avatar" className={cn("flex items-center gap-2", className)} {...props}>
      {Array.from({ length: count }).map((_, i) => (
        <span key={i} className={cn(face, box[size], "shrink-0")}>
          {initialAt(initials, i)}
        </span>
      ))}
    </div>
  )
}

/* FannedStack: hafifce dondurulmus yelpaze dizilimi. */
export function FannedStack({ className, size = "md", count = 3, initials, ...props }: Props) {
  const mid = (count - 1) / 2
  return (
    <div data-slot="styled-avatar" className={cn("flex items-center", className)} {...props}>
      {Array.from({ length: count }).map((_, i) => (
        <span
          key={i}
          className={cn(face, box[size], "shrink-0 origin-bottom ring-2 ring-background", i > 0 && "-ml-4")}
          style={{ rotate: `${(i - mid) * 10}deg` }}
        >
          {initialAt(initials, i)}
        </span>
      ))}
    </div>
  )
}

/* GridAvatars: 2x2 mini izgara (ilk 4 avatar). */
export function GridAvatars({ className, size = "md", count = 4, initials, ...props }: Props) {
  const cells = Math.min(count, 4)
  return (
    <div
      data-slot="styled-avatar"
      className={cn("grid w-fit grid-cols-2 gap-1", className)}
      {...props}
    >
      {Array.from({ length: cells }).map((_, i) => (
        <span key={i} className={cn(face, box[size], "shrink-0")}>
          {initialAt(initials, i)}
        </span>
      ))}
    </div>
  )
}

Manual installs skip the @ai2/tokens theme, so add the token CSS from the theming guide or the tone colors will be missing.

Variations

5 takes on the same idea. Each is its own export, and every one accepts a size prop (sm, md, lg, xl) aligned to the base Button scale.

Stack

Overlapping avatars with a token ring.

ABC

Stack + more

An overlapping stack ending in a plus-N chip.

ABC+5

Row

A spaced row with no overlap.

ABC

Fanned

Slightly rotated, fanned avatars.

ABC

Grid

A compact mini grid of avatars.

ABCD

ai2 Avatar stacks: 5 styled variations on the token system

The ai2 Avatar stacks are a set of 5 decorative button variations from the styled layer of the @ai2 design system, built around grouped avatars. They are free and MIT licensed, and every color comes from a semantic token, so they theme with the rest of ai2 in light and dark.

Motion runs on framer-motion: these are static layouts; no motion library work is required. The styled layer is opt-in, so the dependency only lands if you use it; the base components stay lean. Under reduced motion, there is no motion to reduce.

What is in the ai2 Avatar stacks?

5 exports in one file: Stack, Stack with more, Row, Fanned and Grid. Each renders a native button and takes a size prop (sm, md, lg, xl) aligned to the base Button. They are separate from the base Button on purpose: the base keeps its clean variant, tone and size axes, while the styled layer carries the effects.

You own the file. Copy the one category file and you have all 5 variations, with no runtime dependency on ai2 itself.

Why use it

On-system by construction: Every color resolves to an ai2 semantic token, so the buttons follow your theme in light and dark with no extra work.
Effect without the sprawl: The decorations live in a dedicated styled file, so the base Button keeps its clean, predictable API.
Accessible and honest: Each renders a real button element, keeps a visible focus ring, and respects prefers-reduced-motion.

Features

Token-driven color: No hardcoded hex or oklch; the look recolors with your theme tokens.
framer-motion: these are static layouts; no motion library work is required.
Reduced-motion aware: Under prefers-reduced-motion, there is no motion to reduce.
Size aligned to the base: Every variation takes sm, md, lg and xl matching the base Button height scale, so styled and base buttons line up in a row.

Production tips

Use it for emphasis, not everywhere: Styled buttons draw the eye. Reserve them for the one action you want people to take on a screen, and use the base Button for the rest.
Keep labels as verbs: The decoration adds weight, so a clear action label keeps the button scannable.
Pick one variation per surface: The variations share a family; using two different ones in the same view competes for attention.

Works with the rest of ai2

The Avatar stacks sit alongside the base Button and the rest of the @ai2 registry. They share the same token file, so a styled action next to a base button or a badge stays visually consistent in both modes.