# AvatarStack
## Summary
`AvatarStack` is a [compound component](https://vega-ui.dev/docs/glossary/#compound-component) for overlapping avatar groups such as participants, reviewers, and team previews. The root shares size and variant with each stacked avatar item and turns several identities into one compact grouped display.
## Imports
```tsx
import {
AvatarStack,
AvatarStackItem,
type AvatarGroupProps,
type AvatarGroupSize,
type AvatarGroupStackItemProps,
type AvatarGroupVariant,
} from '@vega-ui/react';
```
## Exported Types
- `AvatarGroupProps`
- `AvatarGroupStackItemProps`
- `AvatarGroupSize`
- `AvatarGroupVariant`
## Minimal Composition
```tsx
import { AvatarFallback, AvatarImage, AvatarStack, AvatarStackItem } from '@vega-ui/react';
const portrait = (hue: number) => `data:image/svg+xml,${encodeURIComponent(``)}`;
export default function MinimalComposition() {
return (
MCOH
);
}
```
## Required Parts
- `AvatarStack`: root layout and shared size/variant context
- `AvatarStackItem`: one stacked avatar item
## Optional Parts
- custom `AvatarImage` and `AvatarFallback` content inside each item
## Composition Order
1. `AvatarStack`
2. repeated `AvatarStackItem`
3. avatar content inside each item
## Variants
- Size: shared avatar size from `2xs` through `2xl`
- Variant: `primary` or `secondary`
- Content: image avatars, fallback avatars, or mixed groups
## Edge Cases
- Very large groups usually need truncation or a `+N` summary pattern at the product level.
- Mixing incompatible avatar sizes in one stack breaks the overlap effect.
- Hover expansion changes spacing subtly and should be checked in dense layouts.
- If explicit identity, roles, or ordering matter more than compactness, a text list or roster UI is usually clearer than a stack.
## Common Mistakes
- Rendering plain avatars without `AvatarStackItem`.
- Mixing arbitrary non-avatar children into the stack.
- Showing too many items without a summarizing pattern.
## Examples
### Basic
#### Basic: reviewers with an overflow count
The first three reviewers are shown and the rest collapse into a “+3” item computed from the list. The stack is a named `role='group'`, each item is a named `role='img'`, and the overflow item lists the hidden names in `title`.
```tsx
import { AvatarFallback, AvatarImage, AvatarStack, AvatarStackItem, Text } from '@vega-ui/react';
const portrait = (hue: number) => `data:image/svg+xml,${encodeURIComponent(``)}`;
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: '' },
];
const maxVisible = 3;
export default function Reviewers() {
const visible = reviewers.slice(0, maxVisible);
const hidden = reviewers.slice(maxVisible);
return (
);
}
```
### Controlled/Stateful
#### Controlled/Stateful: participants joining and leaving
The participant list lives in state; the stack and the summary next to it are derived from it. The summary is a `role='status'` region, so joins and leaves are announced, and the stack is removed entirely when nobody is left.
```tsx
import { useState } from 'react';
import { AvatarFallback, AvatarStack, AvatarStackItem, Button, Text } from '@vega-ui/react';
const people = [
{ name: 'Maria Chen', initials: 'MC' },
{ name: 'Omar Haddad', initials: 'OH' },
{ name: 'Lena Fischer', initials: 'LF' },
{ name: 'Kenji Watanabe', initials: 'KW' },
{ name: 'Ana Souza', initials: 'AS' },
];
export default function CallParticipants() {
const [count, setCount] = useState(2);
const participants = people.slice(0, count);
let summary = 'Nobody is in the call';
if (count === 1) summary = `${participants[0].name} is in the call`;
if (count > 1) summary = `${count} people are in the call`;
return (
);
}
```
### Layout/Overlay
#### Layout/Overlay: participants in a dialog header
A compact `size='xs'` stack next to the dialog title is only a visual hint, so it is `aria-hidden`; the full attendee list below it carries the names. The title leaves room for the close button.
```tsx
import type { CSSProperties } from 'react';
import {
Avatar,
AvatarFallback,
AvatarStack,
AvatarStackItem,
Button,
Dialog,
DialogClose,
DialogContent,
DialogTrigger,
Heading,
Icon,
IconButton,
Text,
} from '@vega-ui/react';
import { XIcon } from '@vega-ui/icons';
const attendees = [
{ name: 'Maria Chen', initials: 'MC', role: 'Organizer' },
{ name: 'Omar Haddad', initials: 'OH', role: 'Engineering' },
{ name: 'Lena Fischer', initials: 'LF', role: 'Design' },
{ name: 'Kenji Watanabe', initials: 'KW', role: 'Product' },
{ name: 'Ana Souza', initials: 'AS', role: 'Support' },
];
export default function ParticipantsDialog() {
return (
);
}
```
### Error
#### Error: photos, failed images and anonymous members
Each item falls back on its own: a broken image shows the initials, a member without a photo shows initials directly, and an anonymous viewer gets an icon with `variant='secondary'`.
```tsx
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(``)}`;
export default function MixedSources() {
return (
MCOHLF
);
}
```
### Edge
#### Edge: from one member to millions
Only four avatars are ever rendered; the remainder is formatted with `Intl.NumberFormat` compact notation (“+1.2K more”, “+2.4M more”). The group’s accessible name carries the exact total, so the shortened visual text is hidden from screen readers.
```tsx
import { useState } from 'react';
import { AvatarFallback, AvatarStack, AvatarStackItem, Button, Text } from '@vega-ui/react';
const letters = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';
const compact = new Intl.NumberFormat('en-US', { notation: 'compact', maximumFractionDigits: 1 });
const maxVisible = 4;
export default function LargeTeam() {
const [total, setTotal] = useState(1248);
const visibleCount = Math.min(total, maxVisible);
const rest = total - visibleCount;
const members = Array.from({ length: visibleCount }, (_, index) => `${letters[index * 3]}${letters[index * 5 + 1]}`);
return (
);
}
```
### Invalid Composition Patterns
#### Avatars rendered directly without `AvatarStackItem`
The group loses overlap and shared context behavior.
#### Mixed arbitrary child markup
The stack should remain a consistent avatar-only structure.
#### Inconsistent avatar sizes in one stack
Overlap masks and hover behavior become visually unstable.