);
}
```
### 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
```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
);
}
```
### 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
```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 (
);
}
```
## 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.