---
url: https://talkjs.com/docs/UI_Components/React/Chatbox
title: '<Chatbox>'

minidoc-source: js
minidoc-lib: components
---

The `<Chatbox>` React component represents a [chatbox UI](/Features/Chat_UIs/#chatbox) for a single conversation, and integrates with the user's TalkJS session.

## ChatboxProps
/** */
export declare interface ChatboxProps extends BaseChatboxProps  {
/** The ID of the conversation to display.
If the conversation doesn't exist or if the current user isn't a participant of the current conversation, a "Conversation not found" message will be displayed (after a timeout). If you create the conversation in parallel (eg via the REST API or via the Data API), it will show in the chatbox automatically. This means that you can safely point a chatbox at a conversation that might not yet exist. This way the chatbox UI and the conversation can load in parallel, which results in snappier UX.
Passing `null` deselects the current conversation and shows an empty panel. This may be useful for Inbox-like scenarios where you want to keep the chatbox loaded, without showing a conversation.
In the background, the Chatbox keeps active subscriptions to recent conversations, so that switching back and forth between conversations has snappy UX. */
conversationId: string|null;
/** Fired when the back button in the chat header is clicked.
By default this back button is only shown inside an inbox on small screens. You can change this behavior in the ChatHeader theme. */
onBackButtonClick?: (event: BackButtonClickEvent)=>void;
/** 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. */
token?: 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. */
tokenFetcher?: ()=>string|Promise<string>;
}
<MType name="ChatboxController">
The `ref` prop lets you obtain a reference to the ChatboxController. For example:

```jsx
const chatbox = useRef(null);
const onSomeEvent = useCallback(() => {
  chatbox.current.setMessageFieldText("Hello, world!");
}, [chatbox]);

return (
  <Chatbox userId="..." ...other props... ref={chatbox} />
);
```
</MType>

## Examples

The following gives some examples of how to use the `Chatbox` component.

### Create a chatbox with an existing user and conversation

Create a chatbox and pass it an existing user, conversation, and the default theme:

```jsx
<Chatbox
  appId="<APP_ID>"
  userId="sample_user_alice"
  conversationId="sample_conversation"
/>
```

### Create a chatbox with a new user and conversation

Install the [`@talkjs/core` package](https://www.npmjs.com/package/@talkjs/core), which lets you read, subscribe to, and update your chat data:

```shell
npm install @talkjs/core
```

```shell
yarn add @talkjs/core
```

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

```js
import { getTalkSession } from '@talkjs/core';
```

Then create the session, user, and conversation:

```jsx
const appId = '<APP_ID>';
const userId = 'sebastian';
const conversationId = 'new_conversation';
const session = getTalkSession({ appId, userId });

useEffect(() => {
  session.currentUser.createIfNotExists({ name: 'Sebastian' });
  const conversation = session.conversation(conversationId);
  conversation.createIfNotExists();
}, [session, conversationId]);
```

Pass the new user and conversation to your chatbox:

```jsx
<Chatbox appId={appId} userId={userId} conversationId={conversationId} />
```

### Hide the chat header

Hide the chat header:

```jsx
<Chatbox
  appId="<APP_ID>"
  userId="sample_user_alice"
  conversationId="sample_conversation"
  chatHeaderVisible={false}
/>
```

### Respond to events

Respond to a sent message event by printing details to the console:

```jsx
<Chatbox
  appId="<APP_ID>"
  userId="sample_user_alice"
  conversationId="sample_conversation"
  onSendMessage={(event) => {
    console.log('Message sent: ', event.message.plaintext);
  }}
/>
```