Avatar

Avatar displays an image, with a fallback to the first letter of the optional name prop.

Best Practices

• Always pass name to ensure a reliable fallback initial.
• Use consistent avatar sizes across list and header contexts.
• Keep custom avatar components lightweight to avoid layout shifts.
• Provide meaningful alt text when wrapping Avatar in custom UI.
• Prefer overriding the Avatar prop rather than replacing entire previews.

Basic Usage

Use Avatar in custom components that replace a header, preview, or similar UI.

Here's an example of using the Avatar component within a custom preview component:

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

const YourCustomChannelPreview = (props) => {
  return (
    <div>
      <Avatar name={props.displayTitle} image={props.displayImage} />
      <div> Other channel info needed in the preview </div>
    </div>
  );
};

<ChannelList Preview={YourCustomChannelPreview} />;

UI Customization

You can also override just the avatar by using the Avatar prop on ChannelHeader and ChannelList.

An example of overriding just the Avatar component in the default ChannelPreviewMessenger component.

const CustomAvatar = (props) => {
  return <Avatar image={props.image} />;
};

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

Props

className

Custom class that will be merged with the default class.

image

The image URL. If it fails to load, the fallback is the first initial (if available).

name

Used to extract a first letter to create the image fallback.

onClick

The click event handler applied to the root div of the component.

onMouseOver

The mouseOver event handler applied to the root div of the component.

user

The full user object for the avatar. This prop isn’t used by the default Avatar component.