Avatar Group

import * as Avatar from '@components/caprice-ui/avatar';
import * as AvatarGroup from '@components/caprice-ui/avatar-group';

const users = [
  {
    name: 'Adrian',
    image: 'https://api.dicebear.com/9.x/open-peeps/svg?seed=Adrian&backgroundColor=b6e3f4',
  },
  {
    name: 'Katherine',
    image: 'https://api.dicebear.com/9.x/open-peeps/svg?seed=Katherine&backgroundColor=ffdfbf',
  },
  {
    name: 'Jessica',
    image: 'https://api.dicebear.com/9.x/open-peeps/svg?seed=Jessica&backgroundColor=ffd5dc',
  },
  {
    name: 'Kingston',
    image: 'https://api.dicebear.com/9.x/open-peeps/svg?seed=Kingston&backgroundColor=d1d4f9',
  },
  {
    name: 'Maria',
    image: 'https://api.dicebear.com/9.x/open-peeps/svg?seed=Maria&backgroundColor=c0aede',
  },
  {
    name: 'Brian',
    image: 'https://api.dicebear.com/9.x/open-peeps/svg?seed=Brian&backgroundColor=bfdbfe',
  },
  {
    name: 'Liliana',
    image: 'https://api.dicebear.com/9.x/open-peeps/svg?seed=Liliana&backgroundColor=f0f9ff',
  },
  {
    name: 'Robert',
    image: 'https://api.dicebear.com/9.x/open-peeps/svg?seed=Robert&backgroundColor=e0e7ff',
  },
  {
    name: 'Liam',
    image: 'https://api.dicebear.com/9.x/open-peeps/svg?seed=Liam&backgroundColor=e0e7ff',
  },
];

export default function Showcase() {
  return (
    <AvatarGroup.Root className="**:data-[slot=avatar]:size-16" spacing={-3}>
      {users.map((user) => (
        <Avatar.Root className="bg-muted" key={user.name}>
          <Avatar.Image src={user.image} />
          <Avatar.Fallback>{user.name.charAt(0)}</Avatar.Fallback>
        </Avatar.Root>
      ))}
    </AvatarGroup.Root>
  );
}

Installation

npx shadcn@latest add @caprice/avatar-group

pnpm dlx shadcn@latest add @caprice/avatar-group

yarn dlx shadcn@latest add @caprice/avatar-group

bunx shadcn@latest add @caprice/avatar-group

npm install @caprice-ui/react

pnpm add @caprice-ui/react

yarn add @caprice-ui/react

bun add @caprice-ui/react

Install the following dependencies:

npm install @base-ui/react lucide-react

pnpm add @base-ui/react lucide-react

yarn add @base-ui/react lucide-react

bun add @base-ui/react lucide-react

Add a cn helper

import { defineConfig, getSchema, type VariantProps } from 'cva';
import { twMerge } from 'tailwind-merge';

export const { cva, cx: cn } = defineConfig({
  hooks: {
    onComplete: (className: string) => twMerge(className),
  },
});

export type { VariantProps };
export { getSchema };

Copy and paste the following code into your project.

'use client';

import { mergeProps } from '@base-ui/react/merge-props';
import { useRender } from '@base-ui/react/use-render';
import { cn } from '@/lib/utils';

/**
 * Displays a group of avatars.
 * Renders a `<div>` element.
 *
 * Documentation: [Caprice UI Avatar Group](https://caprice-ui.com/docs/components/avatar-group)
 */
export namespace Root {
  export type Props = useRender.ComponentProps<'div'> & {
    /**
     * The spacing between the avatars.
     * @default -1.5
     */
    spacing?: number;
  };
}

export function Root({ className, spacing = -1.5, render, ...props }: Root.Props) {
  const defaultProps: useRender.ElementProps<'div'> & { 'data-slot'?: string } = {
    'data-slot': 'avatar-group',
    className: cn('flex flex-wrap items-center space-x-[--spacing(var(--gap))]', className),
    style: {
      '--gap': spacing,
    } as React.CSSProperties,
  };

  return useRender({
    render,
    defaultTagName: 'div',
    props: mergeProps<'div'>(defaultProps, props),
  });
}

Update the import paths to match your project setup.

Usage

import * as AvatarGroup from "@/components/caprice-ui/avatar-group"
import * as Avatar from "@/components/caprice-ui/avatar"

import * as AvatarGroup from "@caprice-ui/react/avatar-group"
import * as Avatar from "@caprice-ui/react/avatar"

<AvatarGroup.Root>
  <Avatar.Root>
    <Avatar.Image src="https://github.com/gomah.png" />
    <Avatar.Fallback>TM</Avatar.Fallback>
  </Avatar.Root>

  <Avatar.Root>
    <Avatar.Image src="https://github.com/fabrelea.png" />
    <Avatar.Fallback>LF</Avatar.Fallback>
  </Avatar.Root>
</AvatarGroup.Root>

Examples

Custom sizes

import * as Avatar from '@components/caprice-ui/avatar';
import * as AvatarGroup from '@components/caprice-ui/avatar-group';

const users = [
  {
    name: 'Adrian',
    image: 'https://api.dicebear.com/9.x/open-peeps/svg?seed=Adrian',
  },
  {
    name: 'Katherine',
    image: 'https://api.dicebear.com/9.x/open-peeps/svg?seed=Katherine',
  },
  {
    name: 'Jessica',
    image: 'https://api.dicebear.com/9.x/open-peeps/svg?seed=Jessica',
  },
  {
    name: 'Kingston',
    image: 'https://api.dicebear.com/9.x/open-peeps/svg?seed=Kingston',
  },
  {
    name: 'Maria',
    image: 'https://api.dicebear.com/9.x/open-peeps/svg?seed=Maria',
  },
  {
    name: 'Brian',
    image: 'https://api.dicebear.com/9.x/open-peeps/svg?seed=Brian',
  },
  {
    name: 'Liliana',
    image: 'https://api.dicebear.com/9.x/open-peeps/svg?seed=Liliana',
  },
  {
    name: 'Robert',
    image: 'https://api.dicebear.com/9.x/open-peeps/svg?seed=Robert',
  },
  {
    name: 'Liam',
    image: 'https://api.dicebear.com/9.x/open-peeps/svg?seed=Liam',
  },
];

export default function AvatarGroupSizes() {
  return (
    <AvatarGroup.Root className="**:data-[slot=avatar]:size-12" spacing={-2}>
      {users.map((user) => (
        <Avatar.Root key={user.name}>
          <Avatar.Image src={user.image} />
          <Avatar.Fallback>{user.name.charAt(0)}</Avatar.Fallback>
        </Avatar.Root>
      ))}
    </AvatarGroup.Root>
  );
}

Custom spacing

import * as Avatar from '@components/caprice-ui/avatar';
import * as AvatarGroup from '@components/caprice-ui/avatar-group';

const users = [
  {
    name: 'Adrian',
    image: 'https://api.dicebear.com/9.x/open-peeps/svg?seed=Adrian',
  },
  {
    name: 'Katherine',
    image: 'https://api.dicebear.com/9.x/open-peeps/svg?seed=Katherine',
  },
  {
    name: 'Jessica',
    image: 'https://api.dicebear.com/9.x/open-peeps/svg?seed=Jessica',
  },
  {
    name: 'Kingston',
    image: 'https://api.dicebear.com/9.x/open-peeps/svg?seed=Kingston',
  },
  {
    name: 'Maria',
    image: 'https://api.dicebear.com/9.x/open-peeps/svg?seed=Maria',
  },
  {
    name: 'Brian',
    image: 'https://api.dicebear.com/9.x/open-peeps/svg?seed=Brian',
  },
  {
    name: 'Liliana',
    image: 'https://api.dicebear.com/9.x/open-peeps/svg?seed=Liliana',
  },
  {
    name: 'Robert',
    image: 'https://api.dicebear.com/9.x/open-peeps/svg?seed=Robert',
  },
  {
    name: 'Liam',
    image: 'https://api.dicebear.com/9.x/open-peeps/svg?seed=Liam',
  },
];

export default function AvatarGroupSpacing() {
  return (
    <AvatarGroup.Root className="**:data-[slot=avatar]:size-12" spacing={-4}>
      {users.map((user) => (
        <Avatar.Root key={user.name}>
          <Avatar.Image src={user.image} />
          <Avatar.Fallback>{user.name.charAt(0)}</Avatar.Fallback>
        </Avatar.Root>
      ))}
    </AvatarGroup.Root>
  );
}

With background

import * as Avatar from '@components/caprice-ui/avatar';
import * as AvatarGroup from '@components/caprice-ui/avatar-group';

const users = [
  {
    name: 'Adrian',
    image: 'https://api.dicebear.com/9.x/open-peeps/svg?seed=Adrian',
  },
  {
    name: 'Katherine',
    image: 'https://api.dicebear.com/9.x/open-peeps/svg?seed=Katherine',
  },
  {
    name: 'Jessica',
    image: 'https://api.dicebear.com/9.x/open-peeps/svg?seed=Jessica',
  },
  {
    name: 'Kingston',
    image: 'https://api.dicebear.com/9.x/open-peeps/svg?seed=Kingston',
  },
  {
    name: 'Maria',
    image: 'https://api.dicebear.com/9.x/open-peeps/svg?seed=Maria',
  },
  {
    name: 'Brian',
    image: 'https://api.dicebear.com/9.x/open-peeps/svg?seed=Brian',
  },
  {
    name: 'Liliana',
    image: 'https://api.dicebear.com/9.x/open-peeps/svg?seed=Liliana',
  },
  {
    name: 'Robert',
    image: 'https://api.dicebear.com/9.x/open-peeps/svg?seed=Robert',
  },
  {
    name: 'Liam',
    image: 'https://api.dicebear.com/9.x/open-peeps/svg?seed=Liam',
  },
];

export default function AvatarGroupBackground() {
  return (
    <AvatarGroup.Root className="**:data-[slot=avatar]:size-12" spacing={-2}>
      {users.map((user) => (
        <Avatar.Root className="bg-input" key={user.name}>
          <Avatar.Image src={user.image} />
          <Avatar.Fallback>{user.name.charAt(0)}</Avatar.Fallback>
        </Avatar.Root>
      ))}
    </AvatarGroup.Root>
  );
}

Installation

Install the following dependencies:

Add a cn helper

Copy and paste the following code into your project.

Update the import paths to match your project setup.

Usage

Examples

Custom sizes

Custom spacing

With background

On this page

Contribute