Avatars

The avatar components draw a user, a channel, or a group of users as a circle. They're the building blocks of the avatars in the channel list, the message list, threads, polls and channel details, and you can render them in your own UI. Every component on this page is exported from stream-chat-react-native and stream-chat-expo.

Best practices

• Render UserAvatar for a user and ChannelAvatar for a channel. They pick the image, the initials, the background color and the accessibility label. Avatar is the base they share, for content of your own.
• Every avatar reads the theme, which OverlayProvider and Chat provide. ChannelAvatar also reads the chat client, so render it inside Chat.
• To change the avatar of every channel list row, override ChannelPreviewAvatar. It's the only override key whose default is one of these components. Elsewhere, override the part that renders the avatar, such as MessageAuthor, MessageRepliesAvatars or MessageUserReactionsAvatar.
• UserAvatar doesn't read user.online. Pass it as showOnlineIndicator, as the SDK does.

Available components

The sizes are named. Each name is a diameter in points:

Avatar

Avatar renders imageUrl with the ImageComponent key of ComponentsContext. Without imageUrl, or once the image fails to load, it renders placeholder instead. After a load error it keeps the placeholder, even if imageUrl changes.

The avatar gets an accessibility label from accessibilityLabel, or, with SDK accessibility on, from name through the avatar.accessibilityLabel key, "Avatar of Cleo". A labeled avatar has the image role. Without a label, screen readers skip it.

UserAvatar

UserAvatar shows user.image. Without one, it shows the initials of user.name, one letter at xs and sm and two at the larger sizes, or a people icon when the user has no name. The background and text colors come from the five avatarPalette colors of the theme, picked by a hash of the user's id, so a user keeps the same color everywhere. The accessibility label is built from user.name, or user.id without one.

With showOnlineIndicator, it adds an OnlineIndicator on the top right of the circle, sized to the avatar.

ChannelAvatar

ChannelAvatar picks what to show from the channel's state:

1. With an image in the channel's data, custom.image, it shows the image on a background picked by a hash of the cid.
2. Otherwise, when more than one member besides the current user is loaded, it shows a UserAvatarGroup of the loaded members.
3. Otherwise, it shows a UserAvatar of the other member, or a people icon in a channel where you're alone.

It re-renders when the image, the members or the other member's presence changes. With SDK accessibility on, screen readers announce it once, as "Direct chat with Cleo" or as "Channel with 5 members". A channel counts as a group when it has a name or more than two members.

The channel edit form uses isPreview to show a picked image, or none, before it's saved.

AvatarGroup and UserAvatarGroup

AvatarGroup places its items in a circle of the given size:

• one item, beside a placeholder with a people icon;
• two items, top left and bottom right;
• three items, one on top and two below;
• four items, in a grid;
• five or more, the first two on top and a BadgeCount with + and the rest below.

UserAvatarGroup renders an AvatarGroup of UserAvatars, each with a 2-point border in semantics.borderCoreInverse, and a presence dot on the top right of the group. The inner avatars are sm, md and xl for a group of lg, xl and 2xl.

UserAvatarGroupProps:

AvatarStack and UserAvatarStack

AvatarStack lays out the first maxVisible items in a row, each shifted over the one before it by overlap, a fraction of the diameter. When there are more items, a BadgeCount with the number of the others follows the row.

UserAvatarStack renders an AvatarStack of UserAvatars, each with a 2-point border in semantics.borderCoreInverse.

UserAvatarStackProps:

Theming

The theme styles the base avatar with avatar.container, avatar.image and avatar.border, and the bordered avatars of UserAvatarStack with avatarStack.userAvatarWrapper. The colors come from the avatarPalette semantic tokens. See Theme object.

Example

A channel list without presence dots, and a row of the people in a call:

import { Text, View } from "react-native";
import type { UserResponse } from "stream-chat";
import { ChannelAvatar, UserAvatarStack } from "stream-chat-react-native";
import type {
  ChannelAvatarProps,
  ComponentOverrides,
} from "stream-chat-react-native";

const ChannelPreviewAvatar = (props: ChannelAvatarProps) => (
  <ChannelAvatar {...props} showOnlineIndicator={false} />
);

// Pass these to WithComponents around ChannelList.
export const avatarOverrides: ComponentOverrides = {
  ChannelPreviewAvatar,
};

export const CallParticipants = ({ users }: { users: UserResponse[] }) => (
  <View style={{ alignItems: "center", flexDirection: "row", gap: 8 }}>
    <UserAvatarStack
      avatarSize="md"
      maxVisible={4}
      overlap={0.3}
      users={users}
    />
    <Text>{users.length} in the call</Text>
  </View>
);

ChannelPreviewView renders ChannelPreviewAvatar with the channel and size="xl".

Related

• Badges: OnlineIndicator and BadgeCount, which the avatars render.
• Channel and thread hooks: useChannelImage and useChannelName, which read what ChannelAvatar shows.
• Channel preview hooks: useChannelPreviewDisplayPresence, the default of showOnlineIndicator.
• Overriding components: WithComponents and the ImageComponent key.