AvatarStack

Patterns

Reviewer Preview

When to use:

• a card or row needs a compact preview of people involved

Composition notes:

• keep the group small
• add a nearby label or count when exact membership matters

Trade-offs:

• fast visual recognition
• less explicit than showing full names

import { AvatarFallback, AvatarImage, AvatarStack, AvatarStackItem, Text } from '@vega-ui/react';

const portrait = (hue: number) => `data:image/svg+xml,${encodeURIComponent(`<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 64 64'><rect width='64' height='64' fill='hsl(${hue} 60% 82%)'/><circle cx='32' cy='25' r='11' fill='hsl(${hue} 35% 42%)'/><path d='M12 64c1-13 9-21 20-21s19 8 20 21z' fill='hsl(${hue} 35% 42%)'/></svg>`)}`;

const reviewers = [
  { name: 'Maria Chen', initials: 'MC', photo: portrait(210) },
  { name: 'Omar Haddad', initials: 'OH', photo: portrait(28) },
  { name: 'Lena Fischer', initials: 'LF', photo: '' },
  { name: 'Kenji Watanabe', initials: 'KW', photo: portrait(150) },
  { name: 'Ana Souza', initials: 'AS', photo: '' },
  { name: 'Tom Becker', initials: 'TB', photo: '' },
];

Mixed Photo And Fallback Group

When to use:

• some users have profile images and others only have initials

Composition notes:

• keep all items at the same size and variant
• provide reasonable alt text for images

Trade-offs:

• robust against incomplete profile data
• visual balance can vary across image/fallback mixes

import { AvatarFallback, AvatarIcon, AvatarImage, AvatarStack, AvatarStackItem } from '@vega-ui/react';
import { User } from '@vega-ui/icons';

const portrait = (hue: number) => `data:image/svg+xml,${encodeURIComponent(`<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 64 64'><rect width='64' height='64' fill='hsl(${hue} 60% 82%)'/><circle cx='32' cy='25' r='11' fill='hsl(${hue} 35% 42%)'/><path d='M12 64c1-13 9-21 20-21s19 8 20 21z' fill='hsl(${hue} 35% 42%)'/></svg>`)}`;

export default function MixedSources() {
  return (
    <AvatarStack role='group' aria-label='Document editors'>
      <AvatarStackItem role='img' aria-label='Maria Chen'>
        <AvatarImage src={portrait(210)} alt='' />
        <AvatarFallback>MC</AvatarFallback>
      </AvatarStackItem>

Modal Header Participants

When to use:

• an overlay header needs a compact participant cue

Composition notes:

• prefer sm or md sizes
• keep the group visually secondary to the main heading

Trade-offs:

• compact and polished
• easy to overload if too many avatars are shown

import type { CSSProperties } from 'react';
import {
  Avatar,
  AvatarFallback,
  AvatarStack,
  AvatarStackItem,
  Button,
  Dialog,
  DialogClose,
  DialogContent,
  DialogTrigger,
  Heading,

Comparison

Quick Decision Rule

Use AvatarStack when several people need to be represented compactly as one grouped display. Use standalone Avatar when only one person is shown.

AvatarStack vs Avatar

Use AvatarStack when:

• several people or entities should be shown together

Use Avatar when:

• one person or entity is enough

AvatarStack vs list of names

Use AvatarStack when:

• compact visual recognition matters more than explicit enumeration

Use a text list when:

• explicit names, roles, or ordering matter more than compactness

Choose This Component When

• several people should be represented in a small space
• visual grouping matters more than explicit enumeration
• the stack is acting as a compact group signal rather than a full roster

Do Not Choose This Component When

• one person is enough
• the UI needs fully explicit names or roles instead of compact avatars

Troubleshooting

The Overlap Effect Looks Wrong

Symptom

The avatars stack awkwardly or spacing jumps unexpectedly.

Likely Cause

Items are not using consistent avatar sizing or are rendered outside AvatarStackItem.

How To Verify

• inspect whether each child is an AvatarStackItem
• compare avatar sizes across the group

Fix

Use AvatarStackItem for every child and keep size/variant consistent.

The Group Is Hard To Understand

Symptom

Users see a compact avatar cluster but cannot tell who or what it represents.

Likely Cause

The surrounding context is missing.

How To Verify

• read the UI without labels or adjacent text

Fix

Add nearby text, counts, or headings that explain the group.

Too Many People Are Rendered

Symptom

The stack becomes visually noisy and unreadable.

Likely Cause

The product is rendering every participant directly.

How To Verify

• count the rendered items in real data scenarios

Fix

Truncate the group and use a summary pattern such as +N at the app level.