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 for group channel representations. A higher-level 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

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 and adds an optional OnlineIndicator.

Usage

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`

ChannelAvatar

AvatarStack