Components

Avatar Group

Stack avatars and collapse overflow into a count.

Install with the CLI

npx @vyui/cli add avatar-group

Overview

VyAvatarGroup overlaps avatars in a compact row, propagates a shared size and color, and can replace hidden children with a +N overflow avatar.

Usage

Child avatars inherit the group's size and color unless they set their own values.

Features and behavior

Fragment and comment nodes are flattened so v-for and v-if work in the default slot.
Children are rendered in reverse order inside a reverse row, preserving the first child's visual stacking priority.
With a positive max, only the first max avatars remain visible.
Hidden children are represented by an internally rendered VyAvatar containing +N.
An absent, invalid, zero, or negative effective max shows all children and no overflow avatar.
A string max is parsed with Number.parseInt.

Props

Prop	Type	Default	Description
`size`	`'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl' \| '3xl'`	`'md'`	Shared child size and overlap spacing.
`color`	`Color`	`'neutral'`	Shared child fallback color.
`max`	`number \| string`	`undefined`	Maximum visible children before rendering `+N`.
`class`	`any`	`undefined`	Classes merged onto the group root.
`ui`	`Partial<Record<AvatarGroupSlot, any>>`	`undefined`	Per-instance theme slot overrides.

Color defaults to primary, secondary, success, info, warning, error, or neutral, and supports registry extensions.

Slots

Slot	Props	Description
`default`	—	Avatar children. Fragments are flattened before limiting and reordering.

Styling and theming

Override globally through appConfig.ui.avatarGroup or locally with ui.

UI slot	Purpose
`root`	Reverse horizontal group layout.
`base`	Border, negative margin, and stacking class applied to every visible and overflow avatar.

The size variant adjusts overlap from -me-1.5 through -me-3; all sizes use a two-pixel white border. The color variant exists to type and propagate the shared color but adds no classes to the group itself.

Accessibility

Each avatar should have meaningful alt text or be wrapped by a labeled interactive control. The generated +N avatar is visual summary text; if the exact hidden identities matter to assistive technology, provide that information elsewhere in the surrounding interface.

Platform notes

The theme uses flex, not inline-flex, because Lynx supports none, flex, grid, and linear display modes.
A white border is used instead of Nuxt UI's web ring-bg token; the default theme is light-mode-oriented.
Group values are passed to descendant VyAvatar components through Vue dependency injection.

Avatar for individual profile imagery.
User for an avatar with text metadata.
Tooltip for exposing additional identity information.

Avatar

Display a profile image with text, icon, and status fallbacks.

Button

A pressable button with color, variant, size, icon, avatar, and loading states.