Pricing

AvatarGroup handbook

v1.8.7 · @snowui-design-system/components

License: Before first reading component documentation, source code, or npm usage instructions, read the complete LICENSE. One review covers the same task and version. Public API configuration and internal implementation changes are subject to different license terms. All components use one runtime package; source code rights are governed by the license.

Overview

Arrange or overlap multiple avatars and show a count for hidden members, for teams, collaborators, and participant lists.

When to use it

Use AvatarGroup for a horizontal or stacked group of participant avatars. Use a regular list for full contact-detail rows.

  • Direct children must declare as="item" to participate in layout and the +N count. Use max to limit visible items.

  • In row, size is each avatar’s size; in stack, it is the group container size. The same value does not produce equal avatar sizes in both layouts.

Quick start

This example shows the recommended basic composition. See the following sections for more scenarios and composition limits.

<script lang="ts">	import { Avatar, AvatarGroup } from '@snowui-design-system/components';	import { Avatar3d04, AvatarAbstract02, AvatarAbstract04, AvatarByewind, AvatarFemale04, AvatarFemale06, AvatarMale03, AvatarMale05 } from '@snowui-design-system/resource-svelte';</script> <AvatarGroup size={40} layout="row" max={4}>	<Avatar as="item" src={AvatarByewind} dataName="ByeWind, maintainer" />	<Avatar as="item" src={AvatarFemale04} dataName="Maya, design" />	<Avatar as="item" src={Avatar3d04} dataName="Leo, components" />	<Avatar as="item" src={AvatarMale03} dataName="Noah, documentation" />	<Avatar as="item" src={AvatarAbstract02} dataName="Ari, accessibility" />	<Avatar as="item" src={AvatarFemale06} dataName="Sofia, research" />	<Avatar as="item" src={AvatarMale05} dataName="Eli, engineering" />	<Avatar as="item" src={AvatarAbstract04} dataName="Kai, community" />	<Avatar as="item" fallbackSeed="user-community-108" aria-label="Additional community member" /></AvatarGroup>

API

Keyword Type Default Description
max number — When omitted, row has no item limit and stack has up to four positions. row shows at most max avatars plus a separate +N; in stack, max includes the +N position and is capped at four. Explicit values are floored at zero; the count label is capped at +99.
layout AvatarGroupLayout "row" row overlaps avatars horizontally; stack arranges them in a circular stack of at most four positions. size and max mean different things in the two modes.
size ResourceSize — 12/16/20/24/28/32/40/48/80. In row mode, this is each avatar's size. In stack mode, it is the group's size; each avatar is sized from the maximum. Inherit the parent size context when no size is provided.
enableResponsive boolean true Enable root Frame responsiveness. AvatarGroup still manages avatar layout and overflow counting; disabling this prop does not disable overflow.
enableContext boolean true Whether to provide a dimensional context for subcomponents (Avatar/Icon/Badge).
children Snippet — Direct as="item" children in order, usually Avatar. Only these participate in layout, hiding, and +N counting.

See the base component documentation for inherited capabilities not redeclared here. This table lists only the named public props declared in this component’s source.

Usage boundaries and details

Combination mode

AvatarGroup uses explicit composition: callers write each <Avatar as="item">. AvatarGroup owns layout, stacking, overflow count, and shared size context, but not Avatar business data, so it does not provide parts.Avatar. Set each Avatar’s distinct props on that instance.

Compose multiple avatars or other children in an overlapping layout, with an automatic numeric overflow count.

Layout model

Main layout model: managed composite layout.

  • The regional structure of AvatarGroup is group root / visible avatar items / overflow count / stack positioning.

  • Avatar, Icon, and Badge children retain their intrinsic atomic or inline-shell layouts. AvatarGroup manages only collection layout, mask cutouts, and overflow count.

  • row and stack are collection layouts, neither a Button-like inline shell nor a three-slot Frame host.

  • The size context is sent to the sub-item through the Frame context, and the arrangement and overlap rules belong to the private logic of AvatarGroup.

User-facing features

  • Multi-avatar layout (supports linear stacking and circular stacking)

  • Automatically display +N overflow count when the quantity is exceeded (up to +99)

  • Combine with any sub-element (not limited to Avatar)

  • Border cutting, stacking and overflowing avatar color matching follow Avatar rules.

2. Visual rules

  1. Layout rules:

    • row: linear arrangement, unlimited quantity; use the border cutting method to stack.

    • stack: Two or three avatars occupy fixed circular positions. With four or more, show three avatars plus +N. On overflow, +N consumes one position: max=2 shows one avatar plus +N, and max=3 shows two plus +N. In row, show max avatars plus a separate count.

  2. Position and level (stack mode):

    • Center point angle (with the center of the circle as the origin and the clockwise as the negative angle):

      • max=2：-45°、135°

      • max=3：-90°、150°、30°

      • max>=4：-45°、-135°、135°、45°

    • Z-order: From bottom to top: red, green, blue, purple.

    • +N position: Always occupies the red position, the lowest layer.

  3. Cutout borders: Stacked avatars use a CSS mask to cut out the border, keeping gaps accurate against any background color.

    • Cutout width: Based on 0.04em relative to avatar size.

    • Row layout: Remove the overlapping part of the left item and the right item.

    • Stack layout: Lower avatars dynamically build a composite mask from the relative coordinates of all overlapping higher avatars for precise cutouts.

  4. Unified sizing:

    • Core rule: One size prop controls the visual size.

    • Stack mode: size measures the container. Avatar size derives from max using 1:1.8, 1:2.0, or 1:2.2 ratios. Internal values retain subpixel precision (for example, 36.36px).

    • Row mode: size measures each avatar; container height follows.

  5. Alignment optimization: The container enforces vertical-align: top and line-height: 0 to ensure that the avatar can be aligned at the pixel level in any font size environment.

  6. Stacking spacing: The overlapping ratio is fixed to 25% (0.25) of the avatar size.

  7. Overflow avatar colors: The +N avatar has black text on #EDEDED. In stack, absolute positioning prevents layout shifts.

  8. Resource matching: Child size is rounded with Math.round so components such as AvatarByewind choose the closest image resolution.

3. Examples

<AvatarGroup size={24}>    <Avatar as="item" src={AvatarByewind} />    <Avatar as="item" src={AvatarByewind} />    <Avatar as="item" /></AvatarGroup>
<AvatarGroup max={2} size={32}>    <Avatar as="item" src={AvatarByewind} />    <Avatar as="item" src={AvatarByewind} />    <Avatar as="item" />    <Avatar as="item" /></AvatarGroup>
<AvatarGroup layout="stack" size={80} max={3}>    <Avatar as="item" src={AvatarByewind} />    <Avatar as="item" src={AvatarByewind} />    <Avatar as="item" />    <Avatar as="item" /></AvatarGroup>

[!IMPORTANT] Overflow background: The +N avatar background is gray #EDEDED, as specified for this component. This is the highest-priority default fallback style.

Add custom notes, business constraints, or examples here.

AvatarGroup style overlay

Read the complete LICENSE first; one review covers the same task, version, and scope.

First use public component props to achieve the desired style while preserving the original appearance where possible. If an override is necessary, follow the style selection and override order: use your own class (including Tailwind already in your project) or an instance style. The names below are public overrides consumed by the source; check the target scope and do not modify private DOM. Choose the appropriate SnowUI token category. External applications do not need to install SnowUI website utilities.

Variable Purpose and default reference
--snowui-avatar-group-item-size-override Single item size (size px, see the component source code for the default value)
--snowui-avatar-group-size-override Overall size (size px, see the component source code for the default value)

Design Guide · Token · Combination Boundary

AvatarGroup type and status

Required props: no named required props.

Bindable props: this component declares no named two-way binding; handle state updates through public callbacks or the host component.

Inheritance: FrameProps. Consult the public Frame documentation for inherited capabilities.

Shared Frame API · Back to API

The following source type declarations are referenced by public props. Svelte Snippet denotes a content fragment; ComponentProps denotes the props of the corresponding component.

AvatarGroupLayout

Source: components/src/components/AvatarGroup.svelte

type AvatarGroupLayout = "row" | "stack";

ResourceSize

Source: components/src/context.ts

export type ResourceSize = 12 | 16 | 20 | 24 | 28 | 32 | 40 | 48 | 80;