<t-conversation-list>

The <t-conversation-list> web component represents a conversation list UI, which displays a list of conversations that the current user is a participant of.

interface ConversationListProps

Properties

appId
: string

Your app's unique TalkJS ID. You can find it on the Settings page of the TalkJS dashboard.

userId
: string

The ID of the current user.

If the given user ID doesn't exist, a "Something went wrong" message will be displayed.

onSelectConversation (optional)
: (event: SelectConversationEvent) => void

Callback that triggers when the user selects a conversation from the list.

Note that updating the selected conversation through the prop **will not** trigger this callback.

Use this callback to have an adjacent chatbox show the correct conversation. See Respond to a select conversation event.

selectedConversationId (optional)
: string

The ID of the conversation currently selected in the list.

Changing the value of this prop will cause the ConversationList UI to update.

Note that updating the selected conversation through this prop **will not** trigger the callback.

theme (optional)
: Partial<Theme>

Lets you override theme components with your own implementations to customize them.

See Custom theme components for more info.

themeCustom (optional)
: any

Arbitrary custom data passed down to the theme.

Whatever data you pass here will be made available for use in theme components through for Chatbox theme components and through for ConversationList theme components.

token (optional)
: string

A token to authenticate the session with.

See the Authentication guide and Token reference for details and examples.

Required when authentication is enabled, otherwise optional.

tokenFetcher (optional)
: () => string | Promise<string>

A function that fetches and returns a new authentication token from your server.

TalkJS calls this function whenever the current token is about to expire. This callback is designed to work with any backend setup. See Refreshable tokens for details and examples.

class ConversationListElement

The t-conversation-list element is a custom element that extends the HTMLElement class. It exposes the following method:

selectConversation

conversationListController.selectConversation(conversationId)

Select a conversation.

This method is called from the theme's ConversationListItem component when the user clicks on the given conversation. You can also call it programmatically from elsewhere to simulate a user click.

This method will trigger the event. In most cases, if you want to change the selected conversation programmatically from outside the conversation list, it's better to pass a different value to the prop instead, as that lets you keep your local state in sync with the props passed to the conversation list.

Parameters

conversationId
: string

Returns

void

Examples

The following examples show how to use the <t-conversation-list> component.

Create a conversation list with an existing user

To create a conversation list and pass it an existing user, use the following:

1<t-conversation-list app-id="<APP_ID>" user-id="sample_user_alice" />

Create a conversation list with a new user

Install the @talkjs/core package, which lets you read, subscribe to, and update your chat data:

1npm install @talkjs/core

Import it into the component where you want to use it:

1import { getTalkSession } from '@talkjs/core';

Then create the session and user:

1appId = '<APP_ID>';
2userId = 'sebastian';
3session: TalkSession | null = null;
4

5ngOnInit() {
6  this.session = getTalkSession({
7    appId: this.appId,
8    userId: this.userId,
9  });
10  this.session.currentUser.createIfNotExists({ name: 'Sebastian' });
11}

Pass the new user to your conversation list:

1<t-conversation-list [app-id]="appId" [user-id]="userId" />

If you're using TalkJS web components without a package manager, see the Create new users and conversations guide.

Respond to a select conversation event

Respond to a select conversation event by switching the chatbox to show the selected conversation.

When a user selects a conversation from the list, the component emits a select-conversation event with the selected conversation’s details. You can handle this event to update a chatbox or perform another action.

1// chat.component.html
2<t-conversation-list
3  app-id="<APP_ID>"
4  user-id="sample_user_alice"
5  [selected-conversation-id]="conversationId()"
6  (selectConversation)="onSelectConversation($event)"
7></t-conversation-list>
8

9<t-chatbox
10  app-id="<APP_ID>"
11  user-id="sample_user_alice"
12  [conversation-id]="conversationId()"
13></t-chatbox>
14

15// chat.component.ts
16conversationId = signal("sample_conversation");
17

18onSelectConversation(event: SelectConversationEvent): void {
19  this.conversationId.set(event.conversation.id);
20}