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

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

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

| Type                |
| ------------------- |
| string \| undefined |

### image

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

| Type           | Default                   |
| -------------- | ------------------------- |
| string \| null | first initial of the name |

### name

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

| Type           |
| -------------- |
| string \| null |

### onClick

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

| Type                                      |
| ----------------------------------------- |
| (event: React.BaseSyntheticEvent) => void |

### onMouseOver

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

| Type                                      |
| ----------------------------------------- |
| (event: React.BaseSyntheticEvent) => void |

### user

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

| Type   |
| ------ |
| Object |


---

This page was last updated at 2026-04-21T09:53:41.631Z.

For the most recent version of this documentation, visit [https://getstream.io/chat/docs/sdk/react/v13/components/utility-components/avatar/](https://getstream.io/chat/docs/sdk/react/v13/components/utility-components/avatar/).