# Avatar

> **Info:** This is release candidate documentation for **Stream Chat React SDK v15**. For the latest stable version, see the [latest version (v14)](https://getstream.io/chat/docs/sdk/react/).

`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](https://getstream.io/chat/docs/sdk/react/v15/ui/customizing/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

```tsx
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:

```tsx
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`:

```tsx
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

| Prop           | Type                                                    | Default                 | Description                                                                                                      |
| -------------- | ------------------------------------------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `size`         | `'2xl' \| 'xl' \| 'lg' \| 'md' \| 'sm' \| 'xs' \| null` | required                | Sets the class `str-chat__avatar--size-{size}`. Another string works with a class of your own; `null` sets none. |
| `className`    | `string`                                                |                         | Added to the default classes.                                                                                    |
| `FallbackIcon` | `ComponentType<ComponentPropsWithoutRef<'svg'>>`        | the `IconUser` icon     | Shown when there's no image and no initials.                                                                     |
| `imageUrl`     | `string`                                                |                         | The image. When it fails to load, the initials show.                                                             |
| `initials`     | `string`                                                | derived from `userName` | The initials to show. More than two characters break the default style.                                          |
| `isOnline`     | `boolean`                                               |                         | Shows an online or offline badge. Without it, there's no badge.                                                  |
| `userName`     | `string`                                                |                         | The title, the image's alt text and the source of the initials.                                                  |

`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:

| Prop             | Type                                                      | Default | Description                                                                                        |
| ---------------- | --------------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------- |
| `displayMembers` | `{ id?: string; imageUrl?: string; userName?: string }[]` |         | The members to show when there's no `imageUrl`. With fewer than two, it shows the first one alone. |
| `badgeSize`      | `BadgeSize`                                               |         | The size of the "+N" badge.                                                                        |

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.

---

For the most recent version of this documentation, visit [https://getstream.io/chat/docs/sdk/react/v15/component-reference/message/avatar/](https://getstream.io/chat/docs/sdk/react/v15/component-reference/message/avatar/).