# Channel List UI
[`ChannelList`](/chat/docs/sdk/react/v11/components/core-components/channel_list/) is a primary navigation component of a chat, used to display and
switch between available channels. Due to the dynamic, real-time nature of chat,
the [`ChannelList`](/chat/docs/sdk/react/v11/components/core-components/channel_list/) component needs to subscribe to and handle many different
types of events to keep the list state up to date. This includes handling new
message events and updates to the existing ones, channel update events, channel
member presence events, and so on.
That's a lot of work, and if done incorrectly, it's easy to miss an important
event. That is why we always recommend building on top of the [`ChannelList`](/chat/docs/sdk/react/v11/components/core-components/channel_list/)
component provided by the SDK, even if you need to do some major customization.
Fortunately, the component itself is very flexible, and basically everything
about it can be customized. It supports
1. [Custom channel preview](#custom-channel-preview)
2. [Custom channel list wrapper](#custom-channel-list-wrapper)
3. [Custom channel list renderer](#custom-channel-list-renderer)
4. [Custom paginator](/chat/docs/sdk/react/v11/guides/channel-list-infinite-scroll/)
This guide takes a deep dive into these customization options.
## Custom Channel Preview
You can think of a channel preview as a single item of the channel list. The
preview should accurately display the current channel state and handle user
interactions to switch to the selected channel.
You can customize the look and behavior of the channel previews by providing a
custom component in the [`Preview`](/chat/docs/sdk/react/v11/components/core-components/channel_list#preview/) prop of the `ChannelList` component. When
rendering previews, `ChannelList` wraps each item with a `ChannelPreview`
wrapper that handles channel events such as new, updated and deleted messages.
This way, you don't have to subscribe to these events yourself, and you can just
grab the latest state from the props instead.
```jsx
// Don't forget to provide filter and sort options as well!
```
Let's implement a simple custom preview:
(See also the complete reference of [the available preview component props](/chat/docs/sdk/react/v11/components/utility-components/channel_preview_ui/).)
The props provided to the preview component are usually sufficient to render the
preview. However, if you need additional data, you can always get it from the
channel state. In this next example, we will add the timestamp of the latest
message in the channel:
One more thing we should add is the click event handler, which should change the
currently active channel. That's easy enough to do:
Note that we've also added an additional class to the preview element if its
channel is currently active (we check this by comparing the id of the active
channel to the id of the current channel.)
## Custom Channel List Wrapper
Channel list wrapper is responsible for rendering the actual items of the
channel list, as well as handling the loading and error states. This is a great
place to plug in your custom component if you want to have a custom loader, or
to add some additional content (like header and footer) to the channel list.
You can do this by providing a custom custom component in the [`List`](/chat/docs/sdk/react/v11/components/core-components/channel_list#list/) prop of the
`ChannelList` component. It will get a bunch of props from the parent
`ChannelList`, including a list of loaded channels, a loading flag, and an error
object (if any).
```jsx
// Don't forget to provide filter and sort options as well!
```
The simplest implementation of the custom channel list wrapper looks like this:
If you need access to the array of channel objects, you can use the
`loadedChannels` prop. Keep in mind, however, that it can update frequently,
resulting in excessive rendering. For this reason, you have to explicitly opt-in
by setting the [`sendChannelsToList`](/chat/docs/sdk/react/v11/components/core-components/channel_list#sendchannelstolist/) prop on the `ChannelList`:
## Custom Channel List Renderer
By default, the [`ChannelList`](/chat/docs/sdk/react/v11/components/core-components/channel_list/) component provided by the SDK renders channel
previews in the same order as the channels were queried. If you want to hook
into the list rendering process, e.g. to add subheadings, group channels, etc.,
you can provide a custom list renderer in the [`renderChannels`](/chat/docs/sdk/react/v11/components/core-components/channel_list#renderchannels/) prop of the
`ChannelList` component.
The function passed in this prop takes a list of loaded channels and a channel
preview component. Note that it is not exactly the component passed in the
[`Preview`](/chat/docs/sdk/react/v11/components/core-components/channel_list#preview/) prop, but rather a version of that component wrapped with the
`ChannelPreview` helper to ensure that all channel event listeners are set up
properly. The `renderChannels` function is only called if the channel list was
successfully loaded and is not empty.
This example adds a separator between read and unread channels:
---
This page was last updated at 2026-04-22T16:43:02.141Z.
For the most recent version of this documentation, visit [https://getstream.io/chat/docs/sdk/react/v11/guides/customization/channel_list_preview/](https://getstream.io/chat/docs/sdk/react/v11/guides/customization/channel_list_preview/).