Chatbox

The Chatbox component represents a chatbox UI for a single conversation.

A Chatbox must be a descendant of Session. It does not need to be a direct descendant.

Props

Name	Type	Description
conversationId	`string`	Required unless `syncConversation` is provided. The id of the conversation to display. If the conversation does not exist, the "Not found" screen is shown.
syncConversation	`Talk.ConversationBuilder` \| `() => Talk.ConversationBuilder`	Required unless `conversationId` is provided. Creates or updates the conversation to display using the supplied ConversationBuilder, then selects it. See example here.
asGuest	`boolean`	Specifies whether to add a user as a guest. Defaults to `false` if not provided.
chatboxRef	`React.Ref`	A React mutable ref object that holds the current TalkJS chatbox object. See an example of how to use `chatboxRef` in your application.
className	`string`	The CSS class name for the div that will contain the chatbox.
highlightedWords	`string[]`	An array of words to highlight in messages. Call with an empty array to disable highlighting.
loadingComponent	`ReactNode`	A React node that will be shown while the chatbox is loading.
style	`CSSProperties`	A CSS style object to style the div that will contain the chatbox.

Chatbox option props

You can use all options in Talk.ChatboxOptions as props to fine-tune the behavior of your chat UI.

If any of these props change, <Chatbox> will apply it directly through a setter such as setFeedFilter. If no such setter exists, it will recreate the Talk.Chatbox.

See below for an example of how to use chatbox options.

Event props

You can pass all events (methods with names starting with on) accepted by the Chatbox in the JavaScript SDK to the Chatbox component as props with the same name.

See below for an example of how to use event props.

Examples

This section gives some examples that demonstrate how to use the Chatbox component.

For all examples, you must create your Chatbox component as a child of your Session component.

Create a chatbox with an existing conversation

Create a chatbox and load the existing conversation with an id of welcome:


1import { Chatbox } from '@talkjs/react';
2
3// ...
4
5<Chatbox
6  conversationId="welcome"
7  style={{ width: 400, height: 600 }}
8  className="chat-container"
9/>;

Create a chatbox and sync a conversation

Create or update user data with the syncConversation prop. This prop expects a callback that uses the regular TalkJS JavaScript SDK to create a ConversationBuilder object with getOrCreateConversation:


1import { useCallback } from 'react';
2import { Chatbox } from '@talkjs/react';
3import Talk from 'talkjs';
4
5// ...
6
7const syncConversation = useCallback((session: Talk.Session) => {
8  // regular TalkJS JavaScript code here
9  const conversation = session.getOrCreateConversation('welcome');
10  conversation.setParticipant(session.me);
11  return conversation;
12}, []);
13
14<Chatbox
15  syncConversation={syncConversation}
16  style={{ width: 400, height: 600 }}
17  className="chat-container"
18/>;

Create a chatbox with a component to display while loading

To display a placeholder component while TalkJS is loading, pass a React node to the loadingComponent prop:


1import { Chatbox } from '@talkjs/react';
2
3// ...
4
5<Chatbox conversationId="welcome" loadingComponent={<h1>Loading..</h1>} />;

Reference a chatbox

To reference a chatbox outside the Chatbox component, assign the underlying Talk.Chatbox object to a ref:


1import { useRef, useCallback } from 'react';
2import { Chatbox } from '@talkjs/react';
3
4const chatbox = useRef<Talk.Chatbox>();
5
6// ...
7
8const onSomeEvent = useCallback(async () => {
9  // do something with the chatbox
10  if (chatbox.current?.isAlive) {
11    chatbox.current.sendLocation();
12  }
13}, []);
14
15<Chatbox conversationId="welcome" chatboxRef={chatbox} />;

The ref will be set once the Talk.Chatbox object has been created, and it will be set back to undefined once it has been destroyed.

Make sure you always check the isAlive property to ensure that the object is not destroyed because React is prone to trigger race conditions here (especially when React.StrictMode is enabled or when using a development setup with hot reloading, both of which cause a lot of destroying).

Respond to events

Respond to events (in this case, sending a message and triggering a custom message action) by printing details to the console:


1import { Chatbox } from '@talkjs/react';
2
3// ...
4
5<Chatbox
6  conversationId="welcome"
7  onSendMessage={(event) => console.log(event.message.text)}
8  onCustomMessageAction={(event) => console.log(event.action)}
9/>;

Add options to customize the chatbox

Customize the chatbox with any options from Talk.ChatboxOptions. This example removes the back button on mobile, and customizes the message field placeholder text:


1<Chatbox
2  showMobileBackButton={false}
3  messageField={{ placeholder: 'Write a message..' }}
4  //...
5/>