---
url: https://talkjs.com/docs/UI_Components/React/Classic/Components/Chatbox
---

# Chatbox

Display a single conversation with a customizable message UI.

Ask a question Copy for LLM [View as Markdown](/docs/UI_Components/React/Classic/Components/Chatbox.md)
The `Chatbox` component represents a [chatbox UI](/docs/Features/Chat_UIs/#chatbox/) for a single conversation.

A `Chatbox` *must* be a descendant of [`Session`](/docs/UI_Components/React/Classic/Components/Session/).
It does not need to be a direct descendant.

## Props

| Name | Type | Description |
| --- | --- | --- |
| ---

**conversation Id**

--- | `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. |
| ---

**sync Conversation**

--- | `Talk.ConversationBuilder` \| `() => Talk.ConversationBuilder` | Required unless `conversationId` is provided.

Creates or updates the conversation to display using the supplied [ConversationBuilder](/docs/UI_Components/JavaScript/Classic/Classic_Data_API/#ConversationBuilder), then selects it. See example [here](/docs/UI_Components/React/Classic/Components/Chatbox/#create-a-chatbox-and-sync-a-conversation). |
| ---

**as Guest**

--- | `boolean` | Specifies whether to add a user as a [guest](/docs/Concepts/Guests/). Defaults to `false` if not provided. |
| ---

**chatbox Ref**

--- | `React.Ref` | A React mutable ref object that holds the current TalkJS chatbox object. See [an example](/docs/UI_Components/React/Classic/Components/Session/#reference-a-session) of how to use `chatboxRef` in your application. |
| ---

**class Name**

--- | `string` | The CSS class name for the div that will contain the chatbox. |
| ---

**highlighted Words**

--- | `string[]` | An array of words to highlight in messages. Call with an empty array to disable highlighting. |
| ---

**loading Component**

--- | `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`](/docs/UI_Components/JavaScript/Classic/Session/#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`](/docs/UI_Components/JavaScript/Classic/Inbox/#Inbox__setFeedFilter). If no such setter exists, it will recreate the `Talk.Chatbox`.

See below for an [example of how to use chatbox options](/docs/UI_Components/React/Classic/Components/Chatbox/#add-options-to-customize-the-chatbox).

### Event props

You can pass all events (methods with names starting with `on`) accepted by the [`Chatbox`](/docs/UI_Components/JavaScript/Classic/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](/docs/UI_Components/React/Classic/Components/Chatbox/#respond-to-events).

## 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`:

```tsx
import { Chatbox } from '@talkjs/react';

// ...

<Chatbox
  conversationId="welcome"
  style={{ width: 400, height: 600 }}
  className="chat-container"
/>;
```

### 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`](/docs/UI_Components/JavaScript/Classic/Classic_Data_API/#ConversationBuilder) object with [`getOrCreateConversation`](/docs/UI_Components/JavaScript/Classic/Session/#Session__getOrCreateConversation):

```tsx
import { useCallback } from 'react';
import { Chatbox } from '@talkjs/react';
import Talk from 'talkjs';

// ...

const syncConversation = useCallback((session: Talk.Session) => {
  // regular TalkJS JavaScript code here
  const conversation = session.getOrCreateConversation('welcome');
  conversation.setParticipant(session.me);
  return conversation;
}, []);

<Chatbox
  syncConversation={syncConversation}
  style={{ width: 400, height: 600 }}
  className="chat-container"
/>;
```

### 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:

```tsx
import { Chatbox } from '@talkjs/react';

// ...

<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](https://react.dev/learn/referencing-values-with-refs):

```tsx
import { useRef, useCallback } from 'react';
import { Chatbox } from '@talkjs/react';

const chatbox = useRef<Talk.Chatbox>();

// ...

const onSomeEvent = useCallback(async () => {
  // do something with the chatbox
  if (chatbox.current?.isAlive) {
    chatbox.current.sendLocation();
  }
}, []);

<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:

```tsx
import { Chatbox } from '@talkjs/react';

// ...

<Chatbox
  conversationId="welcome"
  onSendMessage={(event) => console.log(event.message.text)}
  onCustomMessageAction={(event) => console.log(event.action)}
/>;
```

### Add options to customize the chatbox

Customize the chatbox with any options from [`Talk.ChatboxOptions`](/docs/UI_Components/JavaScript/Classic/Session/#ChatboxOptions). This example removes the back button on mobile, and customizes the message field placeholder text:

```tsx
<Chatbox
  showMobileBackButton={false}
  messageField={{ placeholder: 'Write a message..' }}
  //...
/>
```