ConversationList

ConversationList is mainly responsible for the conversation list feature. It includes the Header and List sections, offering features like conversation search, conversation creation, conversation pinning, and conversation deletion.
This document will detail the basic usage of the component, customization, free combination, and the component's props parameter list.
Conversation List
Conversation Actions
Conversation Search
Create Conversation













Basic Usage

The ConversationList component has no required properties. You can use the ConversationList with the following code.
import { UIKitProvider, ConversationList } from '@tencentcloud/chat-uikit-react';

const App = () => {
return (
<UIKitProvider>
<ConversationList />
</UIKitProvider>
);
};

Props

Parameter Name
Type
Default Value
Indication
enableSearch
Boolean
true
Control whether the conversation search feature is displayed.
enableCreate
Boolean
true
Control whether the create conversation feature is displayed.
enableActions
Boolean
true
Control whether the conversation operation feature is displayed.
actionsConfig
-
Used for custom conversation operation configuration.
Header
ReactElement
Header
Custom Header Component.
List
ReactElement
List
Custom Conversation List Component.
Preview
ReactElement
Custom Conversation Preview Component.
ConversationCreate
ReactElement
ConversationCreate
Custom Conversation Creation Component.
ConversationSearch
ReactElement
Custom Conversation Search Component.
ConversationActions
ReactElement
Custom Conversation Operation Component.
Avatar
ReactElement
Avatar
Custom Avatar Component.
PlaceholderEmptyList
ReactNode
<PlaceHolder type={PlaceHolderTypes.NO_CONVERSATIONS} />
Custom Placeholder Element for an Empty Conversation List.
PlaceholderLoading
ReactNode
<PlaceHolder type={PlaceHolderTypes.LOADING} />
Custom Placeholder Element for Loading Conversation List.
PlaceholderLoadError
ReactNode
<PlaceHolder type={PlaceHolderTypes.WRONG} />
Custom Placeholder Element for Conversation List Load Error.
filter
(conversationList: IConversationModel[]) => IConversationModel[]
-
Function for Filtering Conversation List.
sort
(conversationList: IConversationModel[]) => IConversationModel[]
-
Function for Sorting Conversation List.
onConversationSelect
(conversation: IConversationModel) => void;
-
Callback function after clicking on a conversation, with the parameter being the clicked conversation object.
onBeforeCreateConversation
(params: CreateParams) => CreateParams;
-
Custom operation executed before conversation creation. Parameters are the required parameters for creating a conversation.
onConversationCreate
(conversation: IConversationModel) => void;
-
Callback function after conversation creation, with the parameter being the created conversation object.
className
String
-
Specify the custom CSS name for the root element class.
style
React.CSSProperties
-
Specify the custom style for the root element.

Custom Component

ConversationList provides users with rich and multi-dimensional props interfaces for custom features, UI, modules, etc.
ConversationList component offers multiple replaceable subcomponents, allowing users to customize Header, List, ConversationPreview, ConversationCreate, ConversationSearch, ConversationActions, Avatar, Placeholder, etc. Additionally, users can perform secondary development customization using the default subcomponents.

Basic Feature Toggle

By setting the enableSearch, enableCreate, and enableActions parameters, you can flexibly control the display of search conversations, create conversations, and conversation actions features in the ConversationList.
<ConversationList enableSearch={false} />
<ConversationList enableCreate={false} />
<ConversationList enableActions={false} />
enableSearch={false}
enableCreate={false}
enableActions={false}










Data filtering and sorting

The ConversationList component provides the filterConversation and sortConversation properties, allowing you to filter and sort conversation list data.

Filtering Conversations

To filter conversation list data, you can pass a filter function to the filterConversation property. This function receives an array of IConversationModel as a parameter and should return a new array containing only the conversations that meet your filter criteria.
Here is an example using the filterConversation property to show only conversations with "unread messages":
<ConversationList
filter={(conversationList: IConversationModel[]) =>
conversationList.filter(conversation => conversation.unreadCount > 0)}
/>

Sorting Conversations

To sort conversation list data, you can pass a sorting function to the sortConversation property. This function takes an IConversationModel array as a parameter and should return a new array, sorting the conversations according to your criteria.
Here is an example of using the sortConversation property to sort the conversation list by "Latest News Time Descending":
<ConversationList
sort={(conversationList: IConversationModel[]) =>
conversationList.sort(
(a, b) => (+(b?.lastMessage?.lastTime || 0)) - (+(a?.lastMessage?.lastTime || 0)),
)}
/>
By using the filter and sort properties, you can effectively filter and sort conversation list data according to your needs.

Using actionsConfig

Utilize actionsConfig to control the basic feature of ConversationActions.
For more customization details, please refer to the ConversationActions chapter.
<ConversationList
actionsConfig={{
enablePin: false,
onConversationDelete: (conversation: IConversationModel) => { console.log('Delete conversation success'); },
customConversationActions: {
'custom-actions-1': {
label: 'custom-actions',
onClick: (conversation: IConversationModel) => { console.log(conversation); },
},
},
}}
/>
enablePin: false
enableDelete: false
enableMute: false
customConversationActions













Custom Placeholder

You can customize the list display for different states by passing PlaceholderEmptyList, PlaceholderLoading, and PlaceholderLoadError.
Here is an example of customizing a new PlaceholderLoading:
<ConversationList
PlaceholderEmptyList={<div>Empty List!!!</div>}
/>

Custom Header

ConversationListHeader is responsible for rendering the ConversationList Header, wrapping the default ConversationSearch and ConversationCreate. You can customize it by passing properties like left or right, or you can customize the entire component.

Props

Name
Type
Default
Description
children
ReactNode
-
Custom Conversation List Header Center Component.
When used in <ConversationList>, it will default to include <ConversationSearch> and <ConversationCreate>.
left
ReactElement
-
Custom Conversation List Header Left Component.
right
ReactElement
-
Custom Conversation List Header Right Component.
className
String
-
Specify the custom CSS name for the root element class.
style
React.CSSProperties
-
Specify the custom style for the root element.

Basic customization

The following is an example of adding a new feature button on the right side of the Header component.
import { ConversationList, ConversationListHeader, Icon, IconTypes, IConversationListHeaderProps } from '@tencentcloud/chat-uikit-react';

const CustomConversationListHeader = (props: IConversationListHeaderProps) => {
const CustomIcon = <Icon type={IconTypes.ADD} onClick={() => { console.log('click'); }}></Icon>;
return (
<ConversationListHeader {...props} right={CustomIcon} />
);
};
<ConversationList Header={CustomConversationListHeader} />

Advanced customization

The following is an implementation of a simple conversation grouping feature, differentiating by all conversations, unread conversations, single chat conversations, and group chat conversations. By clicking different grouping buttons, you can execute various filter rules.
before
after










React
CSS
import { useState } from 'react';
import TUIChatEngine, { IConversationModel } from '@tencentcloud/chat-uikit-engine';
import { ConversationList, IConversationListHeaderProps, UIKitProvider } from '@tencentcloud/chat-uikit-react';

const App = () => {
const [currentFilter, setCurrentFilter] = useState<string>('all');
const conversationGroupFilter: Record<string, (conversationList: IConversationModel[]) => IConversationModel[]> = {
all: (conversationList: IConversationModel[]) => conversationList,
unread: (conversationList: IConversationModel[]) => conversationList?.filter((item: IConversationModel) => item.unreadCount > 0),
c2c: (conversationList: IConversationModel[]) => conversationList?.filter((item: IConversationModel) => item.type === TUIChatEngine.TYPES.CONV_C2C),
group: (conversationList: IConversationModel[]) => conversationList?.filter((item: IConversationModel) => item.type === TUIChatEngine.TYPES.CONV_GROUP),
};

const CustomConversationListHeader = (props: IConversationListHeaderProps) => {
return (
<div className="conversation-group-wrapper">
<button className={currentFilter === 'all' ? 'btn-active' : 'btn-default'} onClick={() => setCurrentFilter('all')}>All</button>
<button className={currentFilter === 'unread' ? 'btn-active' : 'btn-default'} onClick={() => setCurrentFilter('unread')}>Unread</button>
<button className={currentFilter === 'c2c' ? 'btn-active' : 'btn-default'} onClick={() => setCurrentFilter('c2c')}>C2C</button>
<button className={currentFilter === 'group' ? 'btn-active' : 'btn-default'} onClick={() => setCurrentFilter('group')}>Group</button>
</div>
);
};

return (
<UIKitProvider>
<ConversationList
style={{ maxWidth: '300px', height: '600px' }}
Header={CustomConversationListHeader}
filter={conversationGroupFilter[currentFilter]}
/>
</UIKitProvider>
);
};
.conversation-group-wrapper {
display: flex;
justify-content: space-around;
align-items: center;
margin: 10px;
font-size: 14px;
.btn-default{
display: flex;
padding: 5px 10px;
border: 1px solid #b3b3b4;
color: #3b3d43;
background-color: transparent;
border-radius: 2px;
}
.btn-active{
display: flex;
padding: 5px 10px;
border: 1px solid #1c66e5;
color: #1c66e5;
background-color: transparent;
border-radius: 2px;
}
}

Custom List

ConversationListContent is responsible for rendering the main list part of ConversationList.
As a wrapper layer, it renders the display data of the current conversation list, which is calculated in the Context, by default filteredAndSortedConversationList.

Props

Name
Type
Default
Description
children
ReactNode
-
Custom Definition Conversation List Content Area Component.
When used in <ConversationList>, it defaults to traversing the filteredAndSortedConversationList as <Preview> list.
empty
Boolean
false
Empty conversation list identifier bit. When used in <ConversationList>, it checks if filteredAndSortedConversationList.length === 0 and passes it.
loading
Boolean
false
The identifier bit for loading the conversation list. When used in <ConversationList>, use useConversationList() to get isLoading and pass it in.
error
Boolean
false
The identifier bit for loading errors in the conversation list. When used in <ConversationList>, use useConversationList() to get isLoadError and pass it in.
PlaceholderEmptyList
ReactNode
<PlaceHolder type={PlaceHolderTypes.NO_CONVERSATIONS} />
Custom Placeholder Element for an Empty Conversation List.
PlaceholderLoading
ReactNode
<PlaceHolder type={PlaceHolderTypes.LOADING} />
Custom Placeholder Element for Loading Conversation List.
PlaceholderLoadError
ReactNode
<PlaceHolder type={PlaceHolderTypes.WRONG} />
Custom Placeholder Element for Conversation List Load Error.
className
String
-
Specify the custom CSS name for the root element class.
style
React.CSSProperties
-
Specify the custom style for the root element.

Basic customization

List component UI effects for different statuses are as follows. Each status's triggering moment is handled internally within ConversationList.
Similarly, you can control the component status through custom definition by passing in empty, loading, error.
import { ConversationList, ConversationListContent, IConversationListContentProps } from '@tencentcloud/chat-uikit-react';

const CustomConversationListContent = (props: IConversationListContentProps) => {
return <ConversationListContent {...props} loading={true} />;
};

<ConversationList List={CustomConversationListContent} />
default
empty={true}
loading={true}
error={true}













Custom ConversationPreview

For details, see the ConversationPreview chapter.
<ConversationList ConversationPreview={CustomConversationPreview} />

Custom ConversationActions

For details, see the ConversationActions chapter.
<ConversationList ConversationActions={CustomConversationActions} />

Custom ConversationSearch

For details, see the ConversationSearch chapter.
<ConversationList ConversationSearch={CustomConversationSearch} />

Custom ConversationCreate

<ConversationList ConversationCreate={CustomConversationCreate} />

Custom Avatar

<ConversationList Avatar={CustomAvatar} />