Avatar

Avatar shows a user: their image, their initials when there's no image or it fails to load, or an icon when there are neither. ChannelAvatar shows a channel: its image, or for a group without one, the avatars of a few members. The Avatar override key replaces the avatars across the UI; Overriding components explains how keys apply.

Best practices

• Pass userName. It's the avatar's title, the image's alt text and the source of the initials.
• Pick a size: it's required, and the stylesheet sizes the avatar from it.
• Make a replacement for the Avatar key render ChannelAvatar for a group, so channel-list rows keep their group avatars.

Basic usage

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

export const UserChip = ({ user }: { user: UserResponse }) => (
  <span className="user-chip">
    <Avatar imageUrl={user.image} size="sm" userName={user.name ?? user.id} />
    {user.name ?? user.id}
  </span>
);

The initials are the first letters of the first and last words of userName, one letter at sizes sm and xs.

Channel avatars

useChannelPreviewInfo returns what a channel's avatar shows, the way the channel list and the channel header get it:

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

export const ChannelBadge = ({ channel }: { channel: Channel }) => {
  const { displayImage, displayTitle, groupChannelDisplayInfo } =
    useChannelPreviewInfo({ channel });

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

• displayImage is the channel's image, or in a channel of two, the other member's image.
• groupChannelDisplayInfo.members lists the members with a name or an image, for a channel of three or more.
• ChannelAvatar shows imageUrl when there is one. Otherwise it shows displayMembers as a group: two to four member avatars, or two and a "+N" badge when there are more than four.

UI customization

The Avatar key reaches the sender's avatar on a message, the reactions dialog, the participants on the replies button, the channel-list rows, mention suggestions, search results, poll votes and channel details. Its components receive ChannelAvatarProps. This one adds a class to every avatar. ChannelAvatar drops className when it draws a single avatar, so the replacement draws a group with ChannelAvatar and one user with Avatar:

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

const SquareAvatar = ({
  badgeSize,
  className,
  displayMembers,
  ...props
}: ChannelAvatarProps) => {
  const classes = className ? `${className} square-avatar` : "square-avatar";

  if (!props.imageUrl && displayMembers && displayMembers.length > 1) {
    return (
      <ChannelAvatar
        {...props}
        badgeSize={badgeSize}
        className={classes}
        displayMembers={displayMembers}
      />
    );
  }

  // As in ChannelAvatar: with no image, show the first member.
  const member = props.imageUrl ? undefined : displayMembers?.[0];

  return (
    <Avatar
      {...props}
      className={classes}
      imageUrl={member?.imageUrl ?? props.imageUrl}
      userName={member?.userName ?? props.userName}
    />
  );
};

const overrides = { Avatar: SquareAvatar };

export const App = () => (
  <WithComponents overrides={overrides}>
    {/* the rest of the app */}
  </WithComponents>
);

ChannelHeader doesn't read the key: pass the component as its Avatar prop. The extractDisplayInfo key changes which user fields become imageUrl and userName.

Props

Avatar

Avatar also passes any div prop, such as onClick or onMouseOver, to its root element.

ChannelAvatar

ChannelAvatar takes the props of Avatar, all optional except size, and:

A group of members takes the sizes '2xl', 'xl' and 'lg', and its member avatars get lg, md and sm in turn. At any other size the member avatars get no size class.

Hooks

• useChannelPreviewInfo({ channel, overrideImage, overrideTitle }) returns displayImage, displayTitle and groupChannelDisplayInfo for a channel.
• useComponentContext() returns the Avatar and extractDisplayInfo overrides in effect, for a component that renders avatars like the SDK's.