Custom headers

You can easily customize (or omit entirely) the chat headers that TalkJS provides out the box. This opens up the possibility to create a completely new header element for your TalkJS UIs and include custom content in them such as product/order information, additional user information or something different altogether.

Removing the default header

To remove the default Chatbox header, simply create a chatbox as you normally would do, but also pass in the optional chatboxOptions object and set showChatHeader to false as shown below.

JavaScript
1const chatbox = session.createChatbox({
2  // Don't use the default header provided by TalkJS
3  showChatHeader: false,
4});

Although the above example uses the Chatbox, the header for the Inbox and Popup UI can similarly be removed.

Creating a custom header

To create a custom header start by moving the div where TalkJS is mounted to inside a new container div which we'll call chatbox-container. This div will be responsible for holding the custom header and the conversation UI. Next, add another div which we'll call chatbox-header to be used for our custom header, as shown in the example below.

HTML
1<!-- Container element for all TalkJS UI elements -->
2<div class="chatbox-container">
3  <!-- Custom TalkJS chat header -->
4  <div class="chatbox-header"></div>
5

6  <!-- container element in which TalkJS will display a chat UI -->
7  <div id="talkjs-container" style="height: 500px"><i>Loading chat...</i></div>
8</div>

Now you can style the new custom-header as you wish or add additional features! For a full example implementation of using custom header see our how-to blog post.

Custom headers for the inbox

The inbox is a more complex UI because it allows the user to switch between conversations they're a part of. It has 2 separate parts: the feed (list of conversations) and the chatbox where the current conversation is shown.

Adjusting the UI for different screen sizes

If the inbox is wider than 640px, it is shown in desktop mode, where these parts are shown next to each other, with the feed on the left and the chatbox on the right (for left-to-right languages). If the inbox is 640px wide or narrower, we only show the feed if no conversation is selected, and only the chatbox if a conversation is selected.

If you look at the CSS in the full example at the end of this tutorial, you'll see how you can adjust the widths of your headers, and whether they are shown, for different screen sizes. The widths and margins are based on TalkJS's default theme, so if you're using a custom theme, you may need to adjust the widths and margins of your headers as well.

Handling the ConversationSelected event

To respond to the user selecting a chat or going back to the feed, you'll want to listen for the conversationSelected event. When the user selects a conversation, your handler will receive a ConversationSelectedEvent object containing information about the selected conversation and its participants. When the user goes back to the feed, the handler is called with null. You can also use this event to update the chatbox header to show the conversation's subject and/or participants.

JavaScript
1inbox.onConversationSelected(({ conversation }) => {
2  if (conversation === null) {
3    // Make sure the feed header is shown, and the chatbox header is hidden.
4  } else {
5    // Make sure the chatbox header is shown, and the feed header is hidden.
6    // Maybe update the chatbox header to reflect the selected chat, with something like this:
7    document.getElementById('chat-header').innerText = conversation.subject;
8  }
9});

Adding a custom "Back" button

By default, we show a button at the top of the chatbox, allowing the user to go back to the feed. If you'd prefer to put this back button in the header, or somewhere else on your site, you can hide the built-in back button by passing showMobileBackButton: false as an option when creating the inbox. Then, when the user clicks your custom back button, call inbox.select(null) and they'll be taken back to the feed. The conversationSelected event is still triggered, even though the selection was done programmatically, so no need to update your layout here.

A complete custom header example

Here's a complete example of a custom header for the inbox. To run and edit this yourself, see our JSFiddle example.

1<div id="container">
2  <div id="header-row">
3    <div id="feed-header">Conversations</div>
4    <div id="chatbox-header">
5      <a href="#" id="back-btn">⬅︎</a>
6      <span id="chat-title">Chat Header</span>
7    </div>
8  </div>
9  <div id="talkjs-container" />
10</div>

In the JavaScript code of this example, replace <APP_ID> with your own TalkJS app ID. You can find your app ID in the Settings tab of the TalkJS dashboard.

For more options to customize your chat interface, see: Themes.