Adding New Features to Existing Themes

Often, when releasing new features we have to add or update elements in our chat UI. However, since the UI is largely rendered using themes, you may need to update your theme to take advantage of new features. If a component in your theme is unchanged from the default, then it is automatically kept up to date. But if a component has been edited, your existing version will be rendered, without the additions we introduced.

Below, you'll find an overview of new features, and a migration guide explaining how to update your theme to take advantage of them.

We have added action buttons and action links, which let you execute custom code in your chat. You can read more about the feature on the Action Buttons and Links page.

Action buttons come with some pre-defined CSS styles in a couple of component templates. To apply these styles, simply copy-paste the following CSS into the correct templates:

CSS for the default theme

UserMessage
1.by-me button[data-action] {
2 color: #0761d1;
3 background-color: white;
4 border: 1px solid white;
5}
6
7.by-me button[data-action]:hover,
8.by-me button[data-action]:active {
9 color: inherit;
10 background-color: transparent;
11}
12
13.by-me button[data-action]:focus-visible {
14 outline: white solid 2px;
15 outline-offset: 2px;
16}
17
18.by-other button[data-action] {
19 color: #111;
20 background-color: transparent;
21 border: 1px solid #525252;
22}
23
24.by-other button[data-action]:hover {
25 color: white;
26 background-color: #111;
27 border: 1px solid #111;
28}
29
30.by-other button[data-action]:active {
31 color: white;
32 background-color: #404040;
33 border: 1px solid #404040;
34}
35
36.by-other button[data-action]:focus-visible {
37 outline: #525252 solid 2px;
38 outline-offset: 2px;
39}
SystemMessage
1.message button[data-action] {
2 border-radius: 0.375rem;
3 font-size: inherit;
4 margin: 1px 0;
5 padding: 0.25rem 0.325rem;
6 cursor: pointer;
7 transition: color 200ms ease-in-out, background-color 200ms ease-in-out,
8 border 200ms ease-in-out;
9
10 color: white;
11 background-color: #007df9;
12 border: 1px solid #007df9;
13}
14
15.message button[data-action]:hover {
16 color: white;
17 background-color: #0761d1;
18 border: 1px solid #0761d1;
19}
20
21.message button[data-action]:active {
22 color: white;
23 background-color: #3291ff;
24 border: 1px solid #3291ff;
25}
26
27.message button[data-action]:focus-visible {
28 outline: #007df9 solid 2px;
29 outline-offset: 2px;
30}
ChatHeader
1.header button[data-action] {
2 border-radius: 0.375rem;
3 font-size: inherit;
4 margin: 1px;
5 padding: 0.25rem 0.325rem;
6 cursor: pointer;
7 transition: color 200ms ease-in-out, background-color 200ms ease-in-out,
8 border 200ms ease-in-out;
9
10 color: #111;
11 background-color: transparent;
12 border: 1px solid #525252;
13}
14
15.header button[data-action]:hover {
16 color: white;
17 background-color: #111;
18 border: 1px solid #111;
19}
20
21.header button[data-action]:active {
22 color: white;
23 background-color: #404040;
24 border: 1px solid #404040;
25}
26
27.header button[data-action]:focus-visible {
28 outline: #525252 solid 2px;
29 outline-offset: 2px;
30}

CSS for the default_dark theme

UserMessage
1.by-me button[data-action] {
2 color: #0761d1;
3 background-color: white;
4 border: 1px solid white;
5}
6
7.by-me button[data-action]:hover {
8 color: inherit;
9 background-color: transparent;
10}
11
12.by-me button[data-action]:focus-visible {
13 outline: white solid 2px;
14 outline-offset: 2px;
15}
16
17.by-other button[data-action] {
18 color: white;
19 background-color: #525252;
20 border: 1px solid #737373;
21}
22
23.by-other button[data-action]:hover {
24 color: #111;
25 background-color: #f7f7f7;
26 border: 1px solid #f7f7f7;
27}
28
29.by-other button[data-action]:active {
30 color: #111;
31 background-color: #ececec;
32 border: 1px solid #ececec;
33}
34
35.by-other button[data-action]:focus-visible {
36 outline: #a3a3a3 solid 2px;
37 outline-offset: 2px;
38}
SystemMessage
1.message button[data-action] {
2 border-radius: 0.375rem;
3 font-size: inherit;
4 margin: 1px 0;
5 padding: 0.25rem 0.325rem;
6 cursor: pointer;
7 transition: color 200ms ease-in-out, background-color 200ms ease-in-out,
8 border 200ms ease-in-out;
9
10 color: #f7f7f7;
11 background-color: #007df9;
12 border: 1px solid #007df9;
13}
14
15.message button[data-action]:hover {
16 color: white;
17 background-color: #3291ff;
18 border: 1px solid #3291ff;
19}
20
21.message button[data-action]:active {
22 color: white;
23 background-color: #0761d1;
24 border: 1px solid #0761d1;
25}
26
27.message button[data-action]:focus-visible {
28 outline: white solid 2px;
29 outline-offset: 2px;
30}
ChatHeader
1.header button[data-action] {
2 border-radius: 0.375rem;
3 font-size: inherit;
4 margin: 1px;
5 padding: 0.25rem 0.325rem;
6 cursor: pointer;
7 transition: color 200ms ease-in-out, background-color 200ms ease-in-out,
8 border 200ms ease-in-out;
9
10 color: white;
11 background-color: #525252;
12 border: 1px solid #737373;
13}
14
15.header button[data-action]:hover {
16 color: #111;
17 background-color: #f7f7f7;
18 border: 1px solid #f7f7f7;
19}
20
21.header button[data-action]:active {
22 color: #111;
23 background-color: #ececec;
24 border: 1px solid #ececec;
25}
26
27.header button[data-action]:focus-visible {
28 outline: #a3a3a3 solid 2px;
29 outline-offset: 2px;
30}

Marking conversations as unread (2023-08-22)

We have added a new built-in Conversation Action to allow users to mark a given conversation as unread. This action renders a small dot inside the conversation's header in the inbox to show that it's been marked as unread. The unread message marker will be removed when the user focuses on the conversation again.

To utilize this feature in your theme you must first add this condition in your ConversationListItem template: use

1<div t:if="{{ isUnread and unreadMessageCount == 0 }}" class="unread-generic-dot"></div>

Afterwards, you must add this unread-generic-dot CSS class so that a small dot is shown when the conversation has been marked as unread. In our default theme we are using the following class:

1.unread-generic-dot {
2 padding: 0.6ex;
3 transform: scale(0.999);
4 border-radius: 999px;
5 background-color: #007DF9;
6}
7
8.conversation-link.active .unread-generic-dot {
9 padding: 0.6ex;
10 transform: scale(0.999);
11 border-radius: 999px;
12 background-color: #fff;
13}

The first definition renders the smaller dot inside the conversation's header while the second definition changes its background color when conversation's active.

Improved attachment thumbnails (2023-07-17)

We improved support for message attachment previews. Previously, the thumbnail was a fixed size and very wide or tall images would get cropped. Now, the thumbnail size will adjust to fit the image, and the entire image will always be shown.

If you have previously edited the MessageBody component in your theme, you will still see some cropping or stretched images. To add full support for improved attachment thumbnails, first add the location class to the <span> containing the location thumbnail, like this:

1<span t:if="{{ body.type == 'location' }}" class="thumbnail location">

Then, update the CSS for the thumbnail class. Previously, it used the height property. With improved thumbnails, we now specify min-height and max-height instead. This allows the thumbnail to grow and shrink based on the height of the image.

For example:

1.thumbnail {
2 display: block;
3 min-height: 100px;
4 max-height: 500px;
5}
6.thumbnail.location {
7 height: 200px;
8}

You can customise the height values to control how big or small the thumbnail becomes.

Unread Message Counter (2023-06-13)

We added support for unread messages counters. These are the typical counters showcasing the number of unread messages for a particular conversation. It appears next to each conversation's subject inside the inbox.

A counter is incremented or decremented whenever a message arrives or is deleted, respectively. It gets reset (and is removed from view) when a conversation is marked as read - typically whenever a conversation is opened by the user.

To add unread message counters to your theme, update the unread message dot markup in the ConversationListItem template to look like this:

1<div t:if="{{ isUnread }}" class="unread-dot">
2 <span t:if="{{ unreadMessageCount > 999 }}">
3 999+
4 </span>
5 <span t:else-if="{{ unreadMessageCount > 0 }}">
6 {{ unreadMessageCount }}
7 </span>
8</div>

The t:if="{{ isUnread}}" attribute ensures that the counter only shows up for conversations with unread messages.

Conversation Actions (2023-03-30)

We added support for conversation actions. They work much the same as message actions, in that the ActionMenu component is now available in the ConversationHeader component. It'll render a button if there are available actions for the current user to perform. If you haven't made any changes to the ChatHeader component of your theme it'll already be there. If you did make changes, create a new theme to see the latest version of our default theme, and see how we're using and styling the ActionMenu in the ChatHeader component. You can then copy this markup and CSS to your own theme, and adapt it to your needs;

Voice messages (2022-10-03)

We added support for playing voice messages directly within TalkJS. Within our themes, this uses the existing mechanism for displaying attachments so it works out of the box, but if you've created a theme before 2022-10-03, you may want to apply these changes to the MessageBody component, in order to differenciate voice messages from regular audio files:

1- <span t:else-if="{{ body.type == 'file' and body.hasThumbnail }}" class="thumbnail {{ body.file.type }}">
2+ <span t:else-if="{{ body.type == 'file' and body.hasThumbnail }}" class="thumbnail {{ body.file.type }} {{body.thumbnailError | then: 'has-error'}}">
3 <Thumbnail file="{{ body.file }}" gradients="{{darkenMenuArea | then: 'top-right'}}"/>
4 </span>
1- <div class="text timestamp-float-{{ floatTimestamp }}">
2+ <div t:if="{{ body.type != 'file' or body.isVoiceMessage == false or body.thumbnailError == true }}" class="text timestamp-float-{{ floatTimestamp }}">
3 <span t:if="{{ isLongEmailMessage }}">
4 <small><i><Icon type="email" /> {{ strings.MESSAGE_SENT_VIA_EMAIL }}</i></small><br/><br/>
5 </span>
1<a class="download-link" href="{{ body.file.url }}" target="_blank" rel="noopener noreferrer">
2 <Icon type="download"/>
3- <span>{{ body.file.formattedFilename }}</span>
4+ <span t:if="{{ body.isVoiceMessage == false }}">{{ body.file.formattedFilename }}</span>
5+ <span t:else><Icon type="microphone" /> {{ strings.VOICE_MESSAGE }} ({{ body.recordingDuration | format_duration }})</span>
6</a>

Then, in the CSS part of the MessageBody:

1+ .thumbnail.audio.has-error {
2+ padding: 0.5rem;
3+ }

Lastly, to show that the last message was a voice message in the conversation list, make the following changes to the ConversationListItem component:

1- <span t:if="{{ lastMessage.body.type == 'file' }}">
2+ <span t:if="{{ lastMessage.body.type == 'file' and lastMessage.body.isVoiceMessage == false }}">
3 <Icon type="image" t:if="{{lastMessage.body.file.type == 'image'}}" />
4 <Icon type="movie" t:if="{{lastMessage.body.file.type == 'video'}}" />
5 <Icon type="attachment" t:if="{{lastMessage.body.file.type == 'other'}}" />
6 <span> {{lastMessage.body.file.filename}}</span>
7</span>
8+ <span t:if="{{ lastMessage.body.type == 'file' and lastMessage.body.isVoiceMessage == true }}">
9+ <span><Icon type="microphone" /> {{ strings.VOICE_MESSAGE }} ({{ lastMessage.body.recordingDuration | format_duration }})</span>
10+ </span>

Status indicator (2022-09-23)

We've added a new StatusIndicator element, which shows if a user is online or offline. If you've created your theme before 2022-09-23, you might have to make some changes to the ChatHeader component in your theme.

To use the Statusindicator element, change these lines in your chatHeader component:

1- <t:set names="{{ conversation.others | map: 'name' | join: ', ' }}" />
1- <div t:if="{{ conversation.formattedSubject }}" class="info">
2- <div class="title">{{ conversation.formattedSubject }}</div>
3- <div class="subtitle">{{ names }}</div>
4- </div>
5- <div t:else class="info">
6- <div class="title">{{ names }}</div>
7- </div>
8+ <div t:if="{{ conversation.formattedSubject }}" class="info">
9+ <div class="title">{{ conversation.formattedSubject }}</div>
10+ <div class="subtitle" >
11+ <div class="inline-block user {{ presenceEnabled | then: 'presence-enabled' }}" t:for="{{ user in conversation.others }}" t:key="{{ user.id }}">
12+ <span>{{user.name}}</span>
13+ <StatusIndicator class="status-indicator" user="{{user}}" />
14+ <span class="participant-separator" t:if="{{ presenceEnabled == false and forloop.last == false }}">, </span>
15+ </div>
16+ </div>
17+ </div>
18+ <div t:else class="info">
19+ <div class="title">
20+ <div class="inline-block user {{ presenceEnabled | then: 'presence-enabled' }}" t:for="{{ user in conversation.others }}" t:key="{{ user.id }}">
21+ <span>{{user.name}}</span>
22+ <StatusIndicator class="status-indicator" user="{{user}}" />
23+ <span class="participant-separator" t:if="{{ presenceEnabled == false and forloop.last == false }}">, </span>
24+ </div>
25+ </div>
26+ </div>
1+ .inline-block {
2+ display: inline-block;
3+ }
4+
5+ .participant-separator {
6+ white-space: pre-wrap;
7+ }
8+
9+ .status-indicator {
10+ margin: 0 0.75rem -1px 0.275rem;
11+ }

Flexible video aspect ratio (2022-09-02)

We added support for displaying videos with a wider range of aspect ratios. If you've created a theme before 2022-09-02, you might have to change some styling in the UserMessage component.

To use the styling of the default UserMessage component, change these lines:

1...
2
3- <span t:if="{{ body.type == 'location' }}" class="thumbnail">
4+ <span t:if="{{ body.type == 'location' }}" class="thumbnail location">
5
6...
7
8 .thumbnail {
9- height: 200px;
10 display: block;
11 }
12
13+ .thumbnail.image, .thumbnail.location {
14+ height: 200px
15+ }
16
17+ .thumbnail.video {
18+ max-height: 400px
19+ }

Emoji reactions (2022-08-18)

We added support for emoji reactions within TalkJS. If you've created a theme before 2022-08-18, you have to add the code for displaying emoji reactions in the UserMessage component. We added two new system components for this:

  • <EmojiReactionButton> renders a button that the user can click to react with a given emoji, or click again to remove their reaction.
  • <AddEmojiReaction> a button that also lets the user add an emoji reaction, but it'll pop up an emoji picker for the user to choose an emoji.

So, before the closing </template> tag, add the following snippet to the UserMessage component:

1<div t:if="{{ reactions and reactions.length > 0 }}" class="emoji-reactions {{ sender.isMe | then: 'by-me' | else: 'by-other' }}">
2 <EmojiReactionButton t:for="{{ reaction in reactions }}" t:key="{{ reaction.emoji }}" class="emoji-reaction {{ reaction.iReacted | then: 'i-reacted' }}" emoji="{{ reaction.emoji }}" numReactions="{{ reaction.numReactions }}" iReacted="{{ reaction.iReacted }}">
3 <span class="reaction">{{ reaction.emoji }}</span>
4 <span class="num-reactions" t:if="{{ reaction.numReactions > 1 }}">{{ reaction.numReactions }}</span>
5 </EmojiReactionButton>
6
7 <AddEmojiReaction class="add-emoji-reaction" t:if="{{ canReact }}">
8 <Icon type="addEmoji" class="icon" />
9 </AddEmojiReaction>
10</div>

Then, to style the emoji reactions, if you used the above snippet, you will have:

  • .emoji-reactions which points to the emoji reactions <div>. This <div> can hav either the by-me or the by-other class, depending whether the message is by the current user or not.
  • .emoji-reaction is the button containing the emoji reaction. This button can also have the i-reacted class if the current user reacted with that emoji. This button also has 2 children:
    • .reaction which is the emoji
    • .num-reactions which is the number of people who reacted with that emoji
  • .add-emoji-reaction is the button for adding an emoji reaction

To use the styling of the default theme, add the following in the <style> section of the UserMessage component:

1.emoji-reactions {
2 margin-top: -0.25rem;
3 margin-bottom: 1.75rem;
4 display: flex;
5 flex-wrap: wrap;
6 gap: 0.25rem;
7}
8.emoji-reactions.by-me {
9 justify-content: flex-end;
10 margin-right: 3.25rem;
11}
12.emoji-reactions.by-other {
13 margin-left: 3.25rem;
14}
15.emoji-reaction {
16 border: 1px solid transparent;
17 margin: 0;
18 padding: 0.2rem 0.55rem;
19 border-radius: 8rem;
20 background-color: #e8ecee;
21}
22.emoji-reaction.i-reacted {
23 background: #1E60E1;
24 border: 1px solid transparent;
25 color: white;
26}
27.emoji-reaction.i-reacted:hover {
28 background: #1E60E1;
29 border: 1px solid transparent;
30}
31.emoji-reaction span {
32 display: inline-block;
33 vertical-align: middle;
34}
35.emoji-reaction .reaction {
36 font-size: 1.25rem;
37}
38.emoji-reaction .num-reactions {
39 padding-left: 0.25rem;
40 font-size: 0.85rem;
41}
42.add-emoji-reaction {
43 border: 1px solid transparent;
44 margin: 0rem;
45 padding: 0.15rem 0.75rem;
46 border-radius: 8rem;
47 background-color: #e8ecee;
48 color: #111;
49}
50.emoji-reaction:hover,
51.add-emoji-reaction:hover {
52 border: 1px solid #b5c0c6;
53}
54.add-emoji-reaction .icon {
55 width: 1.5rem;
56 height: 1.5rem;
57}

After saving the aformentioned changes, emoji reactions will be rendered in the TalkJS UI.

Audio player (2022-08-17)

We added support for playing audio attachments directly within TalkJS. Within our themes, this uses the existing mechanism for displaying attachments so it works out of the box, but if you've created a theme before 2022-08-17, you may want to apply a style tweak to give the player the correct height.

The thumbnail is rendered inside the MessageBody component, so that's where we'll make the change. Since we want to apply the styling only for audio files, we'll add the file type as a class on the <span> that wraps the thumbnail. We can then add some CSS to set the height to auto when there's a thumbnail for an audio file.

MessageBody component:

1...
2
3- <span t:else-if="{{ body.type == 'file' and body.hasThumbnail }}" class="thumbnail">
4+ <span t:else-if="{{ body.type == 'file' and body.hasThumbnail }}" class="thumbnail {{ body.file.type }}">
5 <Thumbnail file="{{ body.file }}" gradients="{{darkenMenuArea | then: 'top-right'}}"/>
6</span>
7
8...
9
10.thumbnail {
11 height: 200px;
12 display: block;
13}
14
15+ .thumbnail.audio {
16+ height: auto;
17+ }

After saving the aformentioned changes, the audio player will have the correct size.

Replies (2022-07-08)

If you want to allow users to reply to messages (described in this changelog entry) and you edited the theme before 08/07/2022 you need to manually pass hasReferencedMessage from UserMessage component to the MessageBody component, and then inside the message body, render the referenced message.

UserMessage component:

1<MessageBody
2 body="{{ body }}"
3 timestamp="{{ timestamp }}"
4 editedAt="{{ editedAt }}"
5 floatTimestamp="auto"
6 showStatus="{{ sender.isMe }}"
7 isLongEmailMessage="{{isLongEmailMessage}}"
8 darkenMenuArea="{{ darkenMenuArea }}"
9 isSystemMessage="{{ false }}"
10+ hasReferencedMessage="{{ hasReferencedMessage }}
11/>

MessageBody component:

1...
2<template>
3
4+ <div t:if="{{ hasReferencedMessage }}" class="referencedMessage">
5+ <ReferencedMessage />
6+ </div>
7
8 <span t:if="{{ body.type == 'location' }}" class="thumbnail">
9 <Thumbnail location="{{ body.location }}" gradients="{{darkenMenuArea | then: 'top-right'}}"/>
10 </span>
11 <span t:else-if="{{ body.type == 'file' and body.hasThumbnail }}" class="thumbnail">
12 <Thumbnail file="{{ body.file }}" gradients="{{darkenMenuArea | then: 'top-right'}}"/>
13 </span>
14...
15
16+ .referencedMessage {
17+ padding: 10px 0px 5px 0px;
18+ }
19
20+ .referencedMessage ~ .text {
21+ padding-top: 0;
22+ }

After saving the aformentioned changes, replies will be rendered in the TalkJS UI.