# SvAvatarGroup
Overlapping, stacked avatars with a "+N" overflow pill - the "assigned to" and
"members" row for cards, tables, and detail panels.
`SvAvatarGroup` takes an array of avatar descriptors and renders them as a neat
overlapping stack, capping the count with `max` and rolling the rest into a
"+N" pill. Each entry is a subset of [SvAvatar](https://svgrid.com/docs/help/ui-components/sv-avatar/) props, so the same
initials-and-color fallback applies to every face.
Related: [SvAvatar](https://svgrid.com/docs/help/ui-components/sv-avatar/) · [SvChip](https://svgrid.com/docs/help/ui-components/sv-chip/) · [Feedback & display overview](https://svgrid.com/docs/help/ui-components/feedback/)
## Installation
Add it with the CLI - this drops a ready-to-edit `SvAvatarGroup` starter into your app:
Prefer to see it first? `npx @svgrid/ui try avatar-group` opens it in a throwaway sandbox - no project needed.
Or install the package and import it directly. `SvAvatarGroup` ships free in
`@svgrid/grid` (dependency-free):
```ts
import { SvAvatarGroup } from '@svgrid/grid'
```
## Example
> Live demo: Command palette (⌘K) + sparklines, avatars, scroll - https://svgrid.com/demos/340-command-palette/
```svelte
```
## Props
| Prop | Type | Default | Description |
| --------- | -------------------------------- | ------- | ------------------------------------------------------------- |
| `avatars` | `ReadonlyArray` | - | The people/entities to stack (see the entry shape below). |
| `max` | `number` | `4` | How many avatars to show before collapsing to "+N". |
| `size` | `sm` \| `md` \| `lg` \| `number`| `md` | Size preset or explicit pixel size, applied to every avatar. |
### The avatar entry shape
Each item is a compact subset of the [SvAvatar](https://svgrid.com/docs/help/ui-components/sv-avatar/) props:
```ts
type AvatarProps = {
name?: string // initials + deterministic fallback color
src?: string // image URL
alt?: string // accessible name
color?: string // override the fallback color
}
```
The overlap and the "+N" pill size scale automatically with `size`.
## Examples
### Assignees on a card
Drop a group into a card footer to show who is on a task:
```svelte
```
### Overflow tuning
Lower `max` in tight rows so more faces roll into the "+N" pill:
```svelte
```
### Mixing images and initials
Entries with a `src` render the photo; entries without fall back to initials -
in the same stack:
```svelte
```
### Reviewers from records
Map your own member objects to the compact entry shape, then let `max` collapse
the tail into "+N" - ideal for an "assigned to" cell or a card footer:
```svelte
{reviewers.length} reviewers
```
> Tip: the overlap and the "+N" pill scale from `size`, so switching to
> `size="sm"` in a dense grid row keeps the stack tight without any manual
> spacing.
## Accessibility
- The stack is a `role="group"`; each face is an [SvAvatar](https://svgrid.com/docs/help/ui-components/sv-avatar/) with
its own `aria-label`, so every visible member is announced.
- The "+N" pill is text, so the hidden count is readable - though for a full
roster, pair the group with an expandable list.
- Faces overlap visually but keep their own labels; color is a supplement, not
the only cue.
## See also
- [Feedback overview](https://svgrid.com/docs/help/ui-components/feedback/) - the whole status and display layer at a glance.
- [SvAvatar](https://svgrid.com/docs/help/ui-components/sv-avatar/) - the single-face primitive this stacks.
- [SvChip](https://svgrid.com/docs/help/ui-components/sv-chip/) - a removable per-person chip when you need names too.
---
SvGrid is the Svelte 5 data grid (`npm install @svgrid/grid`, MIT). This page: https://svgrid.com/docs/help/ui-components/sv-avatar-group/ . All docs: https://svgrid.com/llms.txt