# AvatarStack

`AvatarStack` renders a horizontal row of overlapping avatars, commonly used to display a list of participants. When the number of items exceeds `maxVisible`, the remaining count is shown via a [`BadgeCount`](/chat/docs/sdk/react-native/ui-components/base-ui/badge-count/) component.

A higher-level [`UserAvatarStack`](#useravatarstack) wrapper is also available for convenience when working with user objects.

## Usage

```tsx
import { AvatarStack, UserAvatar } from "stream-chat-react-native";

<AvatarStack
  avatarSize="sm"
  maxVisible={3}
  overlap={0.3}
  items={[
    <UserAvatar user={user1} size="sm" />,
    <UserAvatar user={user2} size="sm" />,
    <UserAvatar user={user3} size="sm" />,
    <UserAvatar user={user4} size="sm" />,
    <UserAvatar user={user5} size="sm" />,
  ]}
/>;
```

## Props

| Prop               | Description                                                                                                                                                                             | Type                       |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
| `items` (required) | Array of React nodes (typically avatar components) to display in the stack.                                                                                                             | `ReactNode[]`              |
| `avatarSize`       | The size key used to determine the diameter of each avatar in the stack. Controls the spacing calculations. Defaults to `'sm'`.                                                         | `'md'` \| `'sm'` \| `'xs'` |
| `maxVisible`       | Maximum number of avatars to display before showing a count badge for the overflow. Defaults to `3`.                                                                                    | `number`                   |
| `overlap`          | A value between 0 and 1 that controls how much each avatar overlaps the previous one. `0` means no overlap (avatars side by side); higher values increase the overlap. Defaults to `0`. | `number`                   |

---

## UserAvatarStack

`UserAvatarStack` is a convenience wrapper around `AvatarStack` that accepts an array of user objects instead of raw React nodes. Each user is automatically rendered as a [`UserAvatar`](/chat/docs/sdk/react-native/ui-components/base-ui/user-avatar/).

### Usage

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

<UserAvatarStack
  users={[user1, user2, user3, user4, user5]}
  avatarSize="sm"
  maxVisible={3}
  overlap={0.25}
/>;
```

### Props

| Prop               | Description                                           | Type                       |
| ------------------ | ----------------------------------------------------- | -------------------------- |
| `users` (required) | Array of user objects to display in the avatar stack. | `UserResponse[]`           |
| `avatarSize`       | Same as `AvatarStack.avatarSize`. Defaults to `'sm'`. | `'md'` \| `'sm'` \| `'xs'` |
| `maxVisible`       | Same as `AvatarStack.maxVisible`. Defaults to `3`.    | `number`                   |
| `overlap`          | Same as `AvatarStack.overlap`. Defaults to `0`.       | `number`                   |


---

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

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