# ChannelHeader

`ChannelHeader` renders the active channel title, subtitle, and avatar.

## Best Practices

- Keep `ChannelHeader` lightweight and move heavier logic into parent components or hooks.
- Let `ChannelHeader` derive the title and image from the active channel unless you need explicit overrides.
- Use a custom header only when you need additional controls or a different layout.
- Inject app-owned sidebar controls through `HeaderStartContent` if your layout uses `ChannelList` or `ThreadList`.
- Do not assume the default header renders `channel.data.subtitle`; v14 derives its subtitle from typing state and online/member status.

## Basic Usage

Render `ChannelHeader` inside `Channel`:

```tsx
import {
  Channel,
  ChannelHeader,
  MessageComposer,
  MessageList,
} from "stream-chat-react";

const App = () => (
  <Channel channel={channel}>
    <ChannelHeader />
    <MessageList />
    <MessageComposer />
  </Channel>
);
```

The default title and image come from the same channel-preview helpers used by `ChannelList`, so direct messages and group channels get synthesized display information automatically.

## Default Behavior

By default, `ChannelHeader`:

- uses `useChannelPreviewInfo()` to derive `displayTitle`, `displayImage`, and group-avatar members
- shows `TypingIndicatorHeader` in the subtitle while other users are typing in the active channel
- otherwise shows online/member status text from `useChannelHeaderOnlineStatus()`
- renders `ChannelAvatar`, which falls back to a group avatar when enough members are available
- renders `HeaderStartContent` when you provide it through `WithComponents` / `ComponentContext`

## UI Customization

You can override the avatar locally and inject app-owned sidebar controls through `WithComponents`:

```tsx
import {
  Avatar,
  Channel,
  ChannelHeader,
  WithComponents,
  type ChannelAvatarProps,
} from "stream-chat-react";

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

const SidebarToggle = () => <button type="button">Toggle sidebar</button>;

<WithComponents overrides={{ HeaderStartContent: SidebarToggle }}>
  <Channel channel={channel}>
    <ChannelHeader Avatar={CustomAvatar} />
  </Channel>
</WithComponents>;
```

If you need to replace the whole header, render your own component instead of `ChannelHeader`. For example, a custom header can still reuse `useChannelPreviewInfo()` and `TypingIndicatorHeader`:

```tsx
import {
  TypingIndicatorHeader,
  useChannelPreviewInfo,
  useChannelStateContext,
  useTypingContext,
} from "stream-chat-react";

const CustomChannelHeader = () => {
  const { channel, channelConfig } = useChannelStateContext();
  const { typing } = useTypingContext();
  const { displayTitle } = useChannelPreviewInfo({ channel });

  const hasTyping =
    channelConfig?.typing_events !== false &&
    Object.values(typing ?? {}).some(({ parent_id }) => !parent_id);

  return (
    <div className="custom-channel-header">
      <div>{displayTitle}</div>
      <div>{hasTyping ? <TypingIndicatorHeader /> : "Custom subtitle"}</div>
    </div>
  );
};
```

## Props

| Prop     | Description                                                                                                                                                                                              | Type        |
| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `Avatar` | Custom avatar component. It receives the same props as `ChannelAvatar`. Defaults to [ChannelAvatar](https://github.com/GetStream/stream-chat-react/blob/master/src/components/Avatar/ChannelAvatar.tsx). | `component` |
| `image`  | Manual image override. When omitted, `ChannelHeader` uses the current channel display image.                                                                                                             | `string`    |
| `title`  | Manual title override. When omitted, `ChannelHeader` uses the current channel display title.                                                                                                             | `string`    |


---

This page was last updated at 2026-05-22T16:32:13.388Z.

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