# React Native AvatarGroup

> A React Native AvatarGroup for iOS, Android and the web: overlapping avatars with rings, a +N for the rest, photos or initials, read as one sentence by screen readers.

# AvatarGroup

A row of overlapping [avatars](./avatar), each ringed in the background color, with a "+N" for the rest: who's in a project, a chat or a meeting.

```tsx
import { AvatarGroup } from 'patine-ui';
```

```tsx live
import { AvatarGroup, Button, Card, HStack, Text, VStack } from 'patine-ui';

const TEAM = [
  { name: 'Maya Cohen', src: 'https://picsum.photos/id/64/120/120' },
  { name: 'Daniel Okafor', src: 'https://picsum.photos/id/91/120/120' },
  { name: 'Ana Lucía Pérez' },
  { name: 'Noah Kim', src: 'https://picsum.photos/id/177/120/120' },
  { name: 'Priya Raman' },
  { name: 'Sven Larsen' },
  { name: 'Lea Martin' },
];

export default function Example() {
  return (
    <Card style={{ padding: 16, maxWidth: 380 }}>
      <VStack gap="md">
        <VStack gap="xs">
          <Text weight="semibold">Spring launch</Text>
          <Text size="sm" color="textSecondary">7 members · updated 2h ago</Text>
        </VStack>
        <HStack justify="space-between">
          <AvatarGroup avatars={TEAM} max={4} size="sm" />
          <Button size="sm" variant="outline">Invite</Button>
        </HStack>
      </VStack>
    </Card>
  );
}
```

## Example: today's meetings

A calendar's agenda: each meeting shows who's invited, up to three faces and a count for the rest, and the group's label reads every name to a screen reader.

```tsx live
import { AvatarGroup, Badge, Button, HStack, List, ListItem, Text, VStack } from 'patine-ui';

const PEOPLE = {
  maya: { name: 'Maya Cohen', src: 'https://picsum.photos/id/64/120/120' },
  daniel: { name: 'Daniel Okafor', src: 'https://picsum.photos/id/91/120/120' },
  ana: { name: 'Ana Lucía Pérez' },
  noah: { name: 'Noah Kim', src: 'https://picsum.photos/id/177/120/120' },
  priya: { name: 'Priya Raman' },
  sven: { name: 'Sven Larsen' },
};

const MEETINGS = [
  { title: 'Design review', time: '10:00 – 10:45', live: true, people: ['maya', 'daniel', 'ana', 'noah', 'priya'] },
  { title: '1:1 with Noah', time: '13:30 – 14:00', people: ['noah'] },
  { title: 'Sprint planning', time: '15:00 – 16:00', people: ['sven', 'priya', 'maya', 'daniel', 'ana', 'noah'] },
] as const;

export default function Example() {
  return (
    <List title="Today, Wednesday" style={{ width: '100%', maxWidth: 460 }}>
      {MEETINGS.map((meeting) => {
        const people = meeting.people.map((id) => PEOPLE[id]);
        return (
          <ListItem
            key={meeting.title}
            title={meeting.title}
            description={meeting.time}
            trailing={
              <HStack gap="sm" align="center">
                <AvatarGroup avatars={people} max={3} size="sm" accessibilityLabel={people.map((p) => p.name).join(', ')} />
                {'live' in meeting ? <Button size="sm">Join</Button> : null}
              </HStack>
            }
          />
        );
      })}
    </List>
  );
}
```

## Accessibility

The group is one image named by the people in it: "Maya Cohen, Daniel Okafor, Ana Lucía Pérez and 4 others". Set `accessibilityLabel` to say something else, such as "7 members".

## Props

Also takes `View` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `avatars` | `{ name?, src? }[]` | — | The people, in order. |
| `max` | `number` | all | Show this many, the last as "+N". |
| `size` | `'sm' \| 'md' \| 'lg' \| number` | `'md'` | Each avatar's size. |
| `shape` | `'circle' \| 'square'` | `'circle'` | As Avatar. |
| `overlap` | `number` | `0.25` | How much each tucks under the one before, as a share of its size. |
| `accessibilityLabel` | `string` | the names | Names the group. |
| `theme`, `design` | | | As every component. |
