Channel list

A channel list shows a complete list of group channels that the current user is a member of by using the ChannelList module. Once the client app is connected to the Sendbird server, you can display the channel list. All chat services built with Sendbird UIKit begin from the channel list.

Usage

To start using the ChannelList module, implement the following code:

import ChannelList from "@sendbird/uikit-react/ChannelList";
<ChannelList />

List of properties

The following table lists the properties of the ChannelList module.

Proprety name	Type	Description
className	string	Specifies the CSS custom name of the class. (Default: `null`)
isTypingIndicatorEnabled	boolean	Determines whether the typing indicator appears on the channel list view. (Default: `False`)
isMessageReceiptStatusEnabled	boolean	Determines whether the message receipt status appears on the channel list view. The possible message receipt statuses are `pending`, `failed`, `sent`, `delivered`, and `read`. (Default: `False`)
disableAutoSelect	boolean	Determines whether the first channel in the channel list view is automatically selected. (Default: `False`)
onBeforeCreateChannel	function	Specifies the prop to execute custom operations before creating a channel. (Default: `null`)
onThemeChange	function	Specifies the prop to receive callback when the theme has changed between `Light` and `Dark`. (Default: `null`)
onProfileEditSuccess	function	Specifies the prop to receive callback when a user profile has been successfully edited. (Default: `null`)
onChannelSelect	function	Specifies the prop to execute custom operations when listing the group channels of the current user. (Default: `null`)
sortChannelList	function	Specifies the function to sort channels in the UI. Don't add or remove channels from the `ChannelList` array when calling this function. (Default: `null`)
queries.channelListQuery	instance	Specifies a GroupChannelListQuery instance to filter channels in the list. (Default: `null`)
renderUserProfile	ReactElement	Renders a customized user profile preview dialog when selecting the profile avatar. The following are given as arguments: - `user`: `User`, `currentUserId`: `userId`, `close`: `function` (Default: `null`)
renderHeader	ReactElement	Renders a customized header component to replace the default header. The following are given as arguments: - `channel`: `GroupChannel`, `user`: `User` (Default: `null`)
renderPlaceHolderError	ReactElement	Renders a customized placeholder for an error status in the channel list. (Default: `null`)
renderPlaceHolderLoading	ReactElement	Renders a customized placeholder for a loading status in the channel list. (Default: `null`)
renderPlaceHolderEmptyList	ReactElement	Renders a customized placeholder for an empty list status when the channel list is empty. (Default: `null`)
renderChannelPreview	ReactElement	Renders a customized channel preview component to replace the default `channelPreview` component. The following are given as arguments: - `channel`: `GroupChannel` - `onLeaveChannel`: `function(channel, callback)` (Default: `null`)
allowProfileEdit	boolean	Determines whether to allow the user to edit their profile. (Default: `true`)

Context

To store and handle data that are used to build a working channel list, Sendbird UIKit provides two context objects: ChannelListProvider and useChannelListContext hook. ChannelListProvider is a provider that manages all the logic and data used in the channel list view. useChannelListContext is a context hook that allows access to the provider's data.

ChannelListProvider

ChannelListProvider contains input props and internal data that handle all the operations in the module. The provider stores data from Chat SDK in real-time and exports them to the UI components. The following code shows how to start using ChannelListProvider.

import { useChannelListContext, ChannelListProvider } from '@sendbird/uikit-react/ChannelList/context';
import ChannelList from '@sendbird/uikit-react/ChannelList';

const MyComponent = () => {
    const channelListState = useChannelListContext();
    return (
        ...render custom component
    );
};

<ChannelListProvider>
    <MyComponent />
<ChannelListProvider/>

const MyPlaceholder = () => {
    const channelListState = useChannelListContext();
    return (
        ...render custom component
    );
};

<ChannelList
    renderPlaceHolderLoading={MyPlaceholder}
/>

List of properties

The following table lists the properties of ChannelListProvider.

Property name	Type	Description
className	string	Specifies the CSS custom name of the class. (Default: `null`)
onBeforeCreateChannel	function	Specifies the prop to execute custom operations before creating a channel. (Default: `null`)
onThemeChange	function	Specifies the prop to receive callback when the theme has changed between `Light` and `Dark`. (Default: `null`)
onProfileEditSuccess	function	Specifies the prop to receive callback when a user profile has been successfully edited. (Default: `null`)
onChannelSelect	function	Specifies the prop to execute custom operations when listing the group channels of the current user. (Default: `null`)
sortChannelList	function	Specifies the function to sort channels in the UI. Don't add or remove channels from the `ChannelList` array when calling this function. (Default: `null`)
queries.channelListQuery	instance	Specifies a GroupChannelListQuery instance to filter channels in the list. (Default: `null`)
allowProfileEdit	boolean	Determines whether to allow the user to edit their profile. (Default: `true`)
renderUserProfile	ReactElement	Renders a customized user profile preview dialog when selecting the user avatar. The following are given as arguments: - `user`: `User`, `currentUserId`: `userId`, `close`: `function` (Default: `null`)
disableUserProfile	boolean	Determines whether to display the user profile preview dialog when selecting the user avatar. If set to `true`, the user profile preview dialog is not shown. (Default: `true`)

useChannelListContext

The useChannelListContext context hook exports the data in the provider to the UI components to create a functional view of the channel list. Every UI component of any layer or level can get access to the data using the context hooks as long as they're inside the provider.

The following code shows how to start using useChannelListContext.

import { useChannelListContext } from '@sendbird/uikit-react/ChannelList/context';

const state = useChannelListContext();

List of properties

The following table lists the properties of useChannelListContext.

Property name	Type	Description
initialized	boolean	Determines whether the channel list is initialized.
loading	boolean	Determines whether the channel list is loading.
allChannels	array of objects	Specifies a list of channels that are loaded in the list.
currentChannel	GroupChannel	Specifies the current user's selected group channel.
channelListQuery	GroupChannelListQuery	Specifies the current user's GroupChannelListQuery.
channelSource	instance	Specifies the instance of GroupChannelListQuery for retrieving channels.

UI components

The UI components in the ChannelList module are the following: ChannelListUI, ChannelListHeader, and ChannelPreview. They're the default set of UI components that compose the channel list view.

ChannelListUI

ChannelListUI is the component that displays the basic screen of the module. It contains placeholders for error and loading statuses and renders the header and channel preview. The following code shows how to implement ChannelListUI.

import ChannelListUI from '@sendbird/uikit-react/ChannelList/components/ChannelListUI';

List of properties

The following table lists the properties of ChannelListUI.

Property name	Type	Description
renderHeader	ReactElement	Renders a customized header component to replace the default header. The following are given as arguments: - `channel`: `GroupChannel`, `user`: `User` (Default: `null`)
renderPlaceHolderError	ReactElement	Renders a customized placeholder for an error status in the channel list. (Default: `null`)
renderPlaceHolderLoading	ReactElement	Renders a customized placeholder for a loading status in the channel list. (Default: `null`)
renderPlaceHolderEmptyList	ReactElement	Renders a customized placeholder for an empty list status when the channel list is empty. (Default: `null`)
renderChannelPreview	ReactElement	Renders a customized channel preview component to replace the default `channelPreview` component. The following are given as arguments: - `channel`: `GroupChannel` - `onLeaveChannel`: `function(channel, callback)` (Default: `null`)

ChannelListHeader

ChannelListHeader is the header component of the ChannelListUI that displays the title and a button to create a new channel.

The following code shows how to implement ChannelListHeader.

import ChannelListHeader from '@sendbird/uikit-react/ChannelList/components/ChannelListHeader';

List of properties

Property name	Type	Description
renderHeader	ReactElement	Renders a customized header to replace the default header. The following are given as arguments: - `channel`: `GroupChannel`, `user`: `User` (Default: `null`)
renderIconButton	ReactElement	Renders a customized icon button to create a new group channel. (Default: `null`)
allowProfileEdit	boolean	Determines whether to allow the user to edit their profile. (Default: `true`)

ChannelPreview

ChannelPreview is a component that displays a single channel in the list item UI. You can customize this component using renderChannelPreview.

The following code shows how to implement ChannelPreview.

import ChannelPreview from '@sendbird/uikit-react/ChannelList/components/ChannelPreview';

List of properties

Property name	Type	Description
channel	instance	Specifies the channel instance shown in the list item. (Default: `null`)
onClick	function	Specifies the prop to select a channel item in the list. (Default: `null`)
renderChannelAction	ReactElement	Renders a customized action on the channel list item when selected. (Default: `null`)
isActive	boolean	Determines whether the channel displayed in the list item UI is currently active. (Default:`false`)