Avatar Group

A component for displaying a collection of avatars with automatic overflow handling and customizable appearance.

Overview

The AvatarGroup component is used to display a collection of avatars in a compact, overlapping layout. It's perfect for showing team members, participants, or any group of users while handling overflow gracefully.

Features

Automatic overflow handling with count indicator
Customizable maximum visible avatars
Adjustable overlap between avatars
Consistent sizing across all avatars
Seamless integration with Avatar component
RTL support

Usage

Basic Group

The simplest way to use the avatar group is with multiple avatars:

<template>
  <MAvatarGroup>
    <MAvatar
      src="https://avatars.githubusercontent.com/u/71938701?v=4"
      alt="User 1"
    />
    <MAvatar
      src="https://avatars.githubusercontent.com/u/72015679?v=4"
      alt="User 2"
    />
    <MAvatar
      icon="i-lucide-user"
      alt="User 3"
    />
  </MAvatarGroup>
</template>

With Max Limit

Limit the number of visible avatars and show a count for the rest:

<template>
  <MAvatarGroup :max="3">
    <MAvatar
      src="https://avatars.githubusercontent.com/u/71938701?v=4"
      alt="User 1"
    />
    <MAvatar
      src="https://avatars.githubusercontent.com/u/72015679?v=4"
      alt="User 2"
    />
    <MAvatar icon="i-lucide-user" alt="User 3" />
    <MAvatar text="JD" alt="User 4" />
    <MAvatar text="AB" alt="User 5" />
  </MAvatarGroup>
</template>

Different Sizes

Avatar groups support all avatar sizes:

<template>
  <div class="space-y-6">
    <MAvatarGroup size="sm">
      <MAvatar src="https://avatars.githubusercontent.com/u/71938701?v=4" alt="User 1" />
      <MAvatar src="https://avatars.githubusercontent.com/u/72015679?v=4" alt="User 2" />
      <MAvatar icon="i-lucide-user" alt="User 3" />
    </MAvatarGroup>

    <MAvatarGroup size="md">
      <MAvatar src="https://avatars.githubusercontent.com/u/71938701?v=4" alt="User 1" />
      <MAvatar src="https://avatars.githubusercontent.com/u/72015679?v=4" alt="User 2" />
      <MAvatar icon="i-lucide-user" alt="User 3" />
    </MAvatarGroup>

    <MAvatarGroup size="lg">
      <MAvatar src="https://avatars.githubusercontent.com/u/71938701?v=4" alt="User 1" />
      <MAvatar src="https://avatars.githubusercontent.com/u/72015679?v=4" alt="User 2" />
      <MAvatar icon="i-lucide-user" alt="User 3" />
    </MAvatarGroup>
  </div>
</template>

Custom Overlap

Adjust the spacing between avatars:

<template>
  <div class="space-y-6">
    <MAvatarGroup overlap="0.5rem">
      <MAvatar src="https://avatars.githubusercontent.com/u/71938701?v=4" alt="User 1" />
      <MAvatar src="https://avatars.githubusercontent.com/u/72015679?v=4" alt="User 2" />
      <MAvatar icon="i-lucide-user" alt="User 3" />
    </MAvatarGroup>

    <MAvatarGroup overlap="1rem">
      <MAvatar src="https://avatars.githubusercontent.com/u/71938701?v=4" alt="User 1" />
      <MAvatar src="https://avatars.githubusercontent.com/u/72015679?v=4" alt="User 2" />
      <MAvatar icon="i-lucide-user" alt="User 3" />
    </MAvatarGroup>
  </div>
</template>

Props

max

number

Maximum number of avatars to display before showing the overflow count.

size

'xs' | 'sm' | 'md' | 'lg' | 'xl'

Size of all avatars in the group.

overlap

string | number

Amount of overlap between avatars. Can be specified in rem or any valid CSS unit.

Slots

default

any

The default slot that should contain Avatar components.

Best Practices

Group sizing:
- Use consistent sizes within each group
- Choose a size appropriate for the context
- Consider the available space when setting max visible avatars
Overlap configuration:
- Use smaller overlap for small avatars
- Use larger overlap for larger avatars
- Maintain consistent overlap across similar groups
Maximum visibility:
- Set reasonable max limits based on available space
- Consider mobile viewports when setting limits
- Ensure the overflow count is easily readable
Accessibility:
- Provide meaningful alt text for each avatar
- Consider adding tooltips for overflow count
- Maintain sufficient color contrast for the overflow count
Performance considerations:
- Optimize avatar images
- Consider lazy loading for large groups
- Use appropriate image sizes based on the avatar size

Callout

A versatile component for highlighting important information with various styles and customization options.

Card

A versatile container component that groups related content and actions with support for header, body, and footer sections.