Skip to content

Search documentation

Search guides, examples, and component APIs.

Quick links
↑↓ NavigateEnter OpenEsc Close
Get started

Documentation navigation

Components / Display

Avatar Group

Arrange related avatars in a compact row. AvatarGroup applies shared size and shape defaults, overlap, and a keyline. It does not own the member list or choose which people are visible.

Last changed in version 0.13.0: Add avatar groups and chips, expand the block gallery, and improve component colors, spacing, and motion.

Interactive showcase

Install

The Avatar dependency is installed automatically. The expandable example also uses Button and Popover; install them with weini add button and weini add popover.

Run in your project
bunx --bun @getweini/cli@latest add avatar-group

Start with this example

Name the group and each visible avatar. In this example, a Button wraps the static count and acts as a Popover trigger for the two additional named members.

Vue
<script setup lang="ts">
import Avatar from './components/ui/avatar/Avatar.vue'
import AvatarFallback from './components/ui/avatar/AvatarFallback.vue'
import AvatarGroup from './components/ui/avatar-group/AvatarGroup.vue'
import AvatarGroupCount from './components/ui/avatar-group/AvatarGroupCount.vue'
import Button from './components/ui/button/Button.vue'
import Popover from './components/ui/popover/Popover.vue'
import PopoverContent from './components/ui/popover/PopoverContent.vue'
import PopoverTrigger from './components/ui/popover/PopoverTrigger.vue'
</script>

<template>
  <AvatarGroup aria-label="Project members" style="--avatar-group-ring: var(--card)">
    <Avatar role="img" aria-label="Ada Lovelace">
      <AvatarFallback aria-hidden="true">AL</AvatarFallback>
    </Avatar>
    <Avatar role="img" aria-label="Grace Hopper">
      <AvatarFallback aria-hidden="true">GH</AvatarFallback>
    </Avatar>
    <Avatar role="img" aria-label="Katherine Johnson">
      <AvatarFallback aria-hidden="true">KJ</AvatarFallback>
    </Avatar>
    <Popover :width="256">
      <PopoverTrigger as-child>
        <Button
          variant="ghost"
          size="md"
          class="w-10 !p-0 !rounded-full"
          aria-label="Show 2 more project members"
        >
          <AvatarGroupCount aria-hidden="true" :count="2" label="2 more project members" />
        </Button>
      </PopoverTrigger>
      <PopoverContent aria-label="More project members">
        <ul class="grid gap-3">
          <li class="flex items-center gap-3">
            <Avatar size="sm" aria-hidden="true">
              <AvatarFallback>D</AvatarFallback>
            </Avatar>
            <span>Dorothy Vaughan</span>
          </li>
          <li class="flex items-center gap-3">
            <Avatar size="sm" aria-hidden="true">
              <AvatarFallback>M</AvatarFallback>
            </Avatar>
            <span>Mary Jackson</span>
          </li>
        </ul>
      </PopoverContent>
    </Popover>
  </AvatarGroup>
</template>

Name the group and each visible avatar. In this example, a Button wraps the static count and acts as a Popover trigger for the two additional named members.

When to use it

Project participants

Show a few project members together while keeping each visible person's name available to assistive technology.

Shared ownership

Summarize visible reviewers, collaborators, or assignees in a compact row. Keep the full member list available elsewhere when people need to inspect or navigate it.

More examples

Shared sizes and shapes

Children inherit the group's size and shape unless an Avatar explicitly sets its own value. Change the keyline token when the group sits on a different surface.

Shared sizes and shapes
<script setup lang="ts">
import Avatar from './components/ui/avatar/Avatar.vue'
import AvatarFallback from './components/ui/avatar/AvatarFallback.vue'
import AvatarGroup from './components/ui/avatar-group/AvatarGroup.vue'

const sizes = ['sm', 'md', 'lg'] as const
</script>

<template>
  <div class="flex flex-wrap items-center gap-6">
    <AvatarGroup
      v-for="size in sizes"
      :key="size"
      :size="size"
      :shape="size === 'lg' ? 'rounded' : 'circle'"
      :aria-label="`${size} project members`"
      style="--avatar-group-ring: var(--card)"
    >
      <Avatar role="img" aria-label="Ada Lovelace">
        <AvatarFallback aria-hidden="true">AL</AvatarFallback>
      </Avatar>
      <Avatar role="img" aria-label="Grace Hopper">
        <AvatarFallback aria-hidden="true">GH</AvatarFallback>
      </Avatar>
      <Avatar role="img" aria-label="Katherine Johnson">
        <AvatarFallback aria-hidden="true">KJ</AvatarFallback>
      </Avatar>
    </AvatarGroup>
    <AvatarGroup size="lg" shape="square" aria-label="Square project members">
      <Avatar role="img" aria-label="Ada Lovelace">
        <AvatarFallback aria-hidden="true">AL</AvatarFallback>
      </Avatar>
      <Avatar role="img" aria-label="Grace Hopper">
        <AvatarFallback aria-hidden="true">GH</AvatarFallback>
      </Avatar>
      <Avatar size="sm" role="img" aria-label="Katherine Johnson, small avatar">
        <AvatarFallback aria-hidden="true">KJ</AvatarFallback>
      </Avatar>
    </AvatarGroup>
  </div>
</template>

Overflow count

Slice the app's member array and compute the remaining count yourself. AvatarGroupCount hides itself when the count is zero or invalid.

Overflow count
<script setup lang="ts">
import { computed } from 'vue'
import Avatar from './components/ui/avatar/Avatar.vue'
import AvatarFallback from './components/ui/avatar/AvatarFallback.vue'
import AvatarGroup from './components/ui/avatar-group/AvatarGroup.vue'
import AvatarGroupCount from './components/ui/avatar-group/AvatarGroupCount.vue'

const maxVisible = 4
const members = [
  { id: 'ada', name: 'Ada Lovelace', initials: 'AL' },
  { id: 'grace', name: 'Grace Hopper', initials: 'GH' },
  { id: 'katherine', name: 'Katherine Johnson', initials: 'KJ' },
]
const visibleMembers = computed(() => members.slice(0, maxVisible))
const overflowCount = computed(() => Math.max(0, members.length - maxVisible))
const overflowLabel = computed(() => `${overflowCount.value} more project members`)
</script>

<template>
  <AvatarGroup aria-label="Project members">
    <Avatar v-for="member in visibleMembers" :key="member.id" role="img" :aria-label="member.name">
      <AvatarFallback aria-hidden="true">{{ member.initials }}</AvatarFallback>
    </Avatar>
    <AvatarGroupCount :count="overflowCount" :label="overflowLabel" />
  </AvatarGroup>
</template>

Complete API

The group accepts size, shape, and native group attributes. AvatarGroupCount accepts a required count and an optional accessible label, plus an optional default slot for its visual count.

AvatarGroup

Complete API for AvatarGroup
NameType or signatureDefaultWhat it does
sizeprop"sm" | "md" | "lg" | undefined"md"Choose the visual size. Medium is the usual default where available.
shapeprop"circle" | "rounded" | "square" | undefined"circle"Choose the component’s visible outline.
defaultslot() => unknownRequiredContent shown inside AvatarGroup.

AvatarGroupCount

Complete API for AvatarGroupCount
NameType or signatureDefaultWhat it does
countpropnumberRequiredControls the count behavior of AvatarGroupCount.
labelpropstring | undefinedNot setVisible or accessible name for this item.
defaultslot((props: { count: number; }) => unknown) | undefinedOptionalContent shown inside AvatarGroupCount.
Public type definitions
Public types
// packages/frameworks/vue/components/avatar-group/types.ts
import type { AvatarProps } from '../avatar/types'

// ------- TYPES -------

export interface AvatarGroupProps {
  size?: AvatarProps['size']
  shape?: AvatarProps['shape']
}

export interface AvatarGroupCountProps {
  count: number
  label?: string
}


// packages/frameworks/vue/components/avatar/types.ts
// ------- IMPORTS -------

import type { avatarShapes, avatarSizes } from './styles'

// ------- TYPES -------

export interface AvatarProps {
  /** Inherits from a parent AvatarGroup, or defaults to `md` when standalone. */
  size?: keyof typeof avatarSizes
  /** Inherits from a parent AvatarGroup, or defaults to `circle` when standalone. */
  shape?: keyof typeof avatarShapes
}

export interface AvatarImageProps {
  src: string
  alt: string
}


// packages/frameworks/vue/components/avatar/styles.ts
// Change Avatar size and shape here; the public visual types follow these keys.
export const avatarSizes = {
  sm: 'size-8 text-xs',
  md: 'size-10 text-sm',
  lg: 'size-12 text-base',
} as const

export const avatarShapes = {
  circle: 'rounded-full',
  rounded: 'rounded-ui',
  square: 'rounded-none',
} as const

Implementation notes

  • AvatarGroup supplies shared size and shape defaults; explicit Avatar props override those defaults. The application owns the visible member list.
  • Compute the overflow count in the application and compose a Button and Popover when users need to reveal additional members.

Accessibility and localization

  • Give AvatarGroup an aria-label that names the set. Give each visible Avatar a name with aria-label, or use a meaningful AvatarImage alt.
  • Use AvatarFallback for initials or another short visual substitute. Hide fallback text from assistive technology when the Avatar itself already has an accessible name.
  • Localize AvatarGroupCount's label. A custom default slot changes only its visual text; the label is its accessible name.
  • AvatarGroupCount is a static visual label; an enclosing Button and Popover provide the optional action and member list. Keep the count hidden from assistive technology inside the Button and give the Button a localized accessible name.
  • The count component alone does not expose names for hidden members. The application supplies any disclosure and list content.

Source contract and editing guidance