Avatar

Avatar renders a user avatar image with an initials or icon fallback.

Best Practices

• Always pass userName so the fallback initials and title attribute stay meaningful.
• Pick a size explicitly and keep it consistent within the same surface.
• Use ChannelAvatar when rendering channels, because it accepts channel display members and computes the visible stack automatically.
• Keep custom avatar wrappers lightweight to avoid layout shifts in lists.
• Use getChannelDisplayImage(channel) when you need the same direct-message image fallback as the SDK.

Basic Usage

Use Avatar in your own headers, previews, or message surfaces:

import { Avatar } from "stream-chat-react";

const CustomUserChip = () => (
  <Avatar imageUrl={user.image} size="md" userName={user.name} />
);

Channel Avatars

For channel previews and headers, prefer ChannelAvatar instead of raw Avatar.

Pass displayMembers when you have group-channel member data. ChannelAvatar and GroupAvatar compute the visible members and overflow badge internally, so you do not need to provide a separate overflow count.

import {
  ChannelAvatar,
  getChannelDisplayImage,
  useChannelPreviewInfo,
} from "stream-chat-react";

const CustomChannelAvatar = ({ channel }) => {
  const { displayTitle, groupChannelDisplayInfo } = useChannelPreviewInfo({
    channel,
  });

  return (
    <ChannelAvatar
      displayMembers={groupChannelDisplayInfo.members}
      imageUrl={getChannelDisplayImage(channel)}
      size="xl"
      userName={displayTitle}
    />
  );
};

UI Customization

You can pass a custom avatar component into surfaces such as ChannelHeader or ChannelListItemUI.

import {
  Avatar,
  type ChannelAvatarProps,
  ChannelList,
  WithComponents,
} from "stream-chat-react";

const CustomAvatar = ({
  imageUrl,
  size = "xl",
  userName,
}: Partial<ChannelAvatarProps>) => (
  <Avatar imageUrl={imageUrl} size={size} userName={userName} />
);

<WithComponents overrides={{ Avatar: CustomAvatar }}>
  <ChannelList />
</WithComponents>;

Props