This is beta documentation for Stream Chat React SDK v14. For the latest stable version, see the latest version (v13) .

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 can switch to a group avatar 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.

ChannelAvatar renders:

a single Avatar for one-to-one channels
a GroupAvatar when displayMembers contains at least two members

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

const CustomChannelAvatar = ({ channel }) => {
  const displayTitle = useChannelDisplayName(channel);

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

UI Customization

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

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

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

<ChannelList
  Preview={(props) => (
    <ChannelPreviewMessenger {...props} Avatar={CustomAvatar} />
  )}
/>;

Props

Prop	Description	Type
`className`	Additional class names merged with the default avatar classes.	`string`
`imageUrl`	Avatar image URL. If the image fails to load, `Avatar` falls back to initials or the default icon.	`string`
`isOnline`	When provided, shows the online/offline badge.	`boolean`
`onClick`	Click handler applied to the root element.	`(event: React.BaseSyntheticEvent) => void`
`onMouseOver`	Mouse-over handler applied to the root element.	`(event: React.BaseSyntheticEvent) => void`
`size`	Avatar size.	`"2xl" \| "xl" \| "lg" \| "md" \| "sm" \| "xs" \| null`
`userName`	Name used for the title attribute and the initials fallback.	`string`

UI Components

BaseImage