# AvatarGroup

`AvatarGroup` renders a composite avatar layout that arranges multiple avatar items in a grid-style formation. It supports 1 to 4+ items and automatically adjusts the layout based on the number of items provided.

The component is used by [`ChannelAvatar`](/chat/docs/sdk/react-native/ui-components/base-ui/channel-avatar/) for group channel representations. A higher-level [`UserAvatarGroup`](#useravatargroup) wrapper is also available for convenience when working with user objects.

## Layout Rules

| Item Count | Layout                                                        |
| ---------- | ------------------------------------------------------------- |
| 1          | Single avatar + people icon placeholder                       |
| 2          | Two avatars side by side (top-start, bottom-end)              |
| 3          | Three avatars (top-center, bottom-start, bottom-end)          |
| 4          | Four avatars in a 2×2 grid                                    |
| 5+         | First two avatars + a badge count showing the remaining count |

## Usage

```tsx
import { AvatarGroup, Avatar } from "stream-chat-react-native";

<AvatarGroup
  size="xl"
  items={[
    <Avatar size="md" imageUrl="https://example.com/a.png" />,
    <Avatar size="md" imageUrl="https://example.com/b.png" />,
    <Avatar size="md" imageUrl="https://example.com/c.png" />,
  ]}
/>;
```

## Props

| Prop               | Description                                                                                                                                                    | Type                        |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- |
| `size` (required)  | The overall size of the avatar group container. Size mapping: `'2xl'` (64x64), `'xl'` (48x48), `'lg'` (44x44).                                                 | `'lg'` \| `'xl'` \| `'2xl'` |
| `items` (required) | Array of React nodes (typically `Avatar` components) to arrange in the group layout. The component automatically selects the layout based on the array length. | `ReactNode[]`               |

---

## UserAvatarGroup

`UserAvatarGroup` is a convenience wrapper around `AvatarGroup` that accepts an array of user objects instead of raw React nodes. It automatically renders each user as a [`UserAvatar`](/chat/docs/sdk/react-native/ui-components/base-ui/user-avatar/) and adds an optional [`OnlineIndicator`](/chat/docs/sdk/react-native/ui-components/base-ui/online-indicator/).

### Usage

```tsx
import { UserAvatarGroup } from "stream-chat-react-native";

<UserAvatarGroup users={[user1, user2, user3]} size="xl" showOnlineIndicator />;
```

### Props

| Prop                  | Description                                                                                               | Type                        |
| --------------------- | --------------------------------------------------------------------------------------------------------- | --------------------------- |
| `users` (required)    | Array of user objects to display in the avatar group.                                                     | `UserResponse[]`            |
| `size` (required)     | The overall size of the avatar group container. Same as `AvatarGroup.size`.                               | `'lg'` \| `'xl'` \| `'2xl'` |
| `showOnlineIndicator` | Whether to display an online presence indicator in the top-right corner of the group. Defaults to `true`. | `boolean`                   |


---

This page was last updated at 2026-04-17T17:33:46.612Z.

For the most recent version of this documentation, visit [https://getstream.io/chat/docs/sdk/react-native/ui-components/base-ui/avatar-group/](https://getstream.io/chat/docs/sdk/react-native/ui-components/base-ui/avatar-group/).