Advanced customization Early Access
NOTE
This feature is released as Early Access.
Besides basic customization, there are further advanced customization possibilities utilizing CSS variables, where you can define themes with custom styling and apply them at widget runtime.
By enabling this option, you can align the chat widget's appearance with your brand's logo, colors, and visual identity.
If you want to use the advanced customization option, the following is required:
- Activated LIVECHAT_CUSTOMIZATION feature flag.
- On the Live Chat configuration application, declare customization configuration (structure of the JSON described later).
- To set the current theme of the widget, use JS SDK API → liveChat('set_theme', 'theme_name'), e.g., liveChat('set_theme', 'dark')
Customization configuration structure
The ability to define themes and styles for the widget is facilitated by setting the theme in the JSON file. This file's content should then be inserted into the input text area on the widget configuration page. The structure of the JSON is as follows:
{
"themes": {
"default": {
"lc-chat-message-agent-bubble-background-color": "#f7f7f7",
"lc-chat-message-agent-bubble-text-color": "#000",
"another_variable_name": "variable_value"
},
"dark": {
"lc-chat-message-agent-bubble-background-color": "#000",
"lc-chat-message-agent-bubble-text-color": "#f7f7f7",
//...
},
"another_theme_name": {
//...
}
}
}
When defining themes, the only required theme name is default. This theme is applied by default when advanced customization configuration is detected, and a widget is initiated on your page (if set_theme API was not called before). The selection of other themes and their respective names relies on your preferences. For instance, as shown above, the theme named "dark" could be assigned to the widget when the user activates dark mode on their device/browser.
Each theme is represented as an object of key and value pairs. The key represents the name of the CSS variable, and the value represents the CSS value as a string.
You do not need to add all supported CSS variables in your theme definition, only those for which you want to override their default values.
Supported CSS variables
Each CSS variable name follows the atomic design. They are declared based on the following structure:
lc-{section}-{organism}-{molecules}-{atoms}
- lc - prefix for all CSS variables related to Live Chat
- section - main parts that build the Live Chat widget (header, chat, footer, etc.)
- organism - larger items that exist within a section that can be broken down into molecules (form, carousel, thread item, etc.)
- molecules - smallest building blocks, as Live Chat is written in React you can imagine it as the bottom layer of react components (header title, avatar, bubble, etc.)
- atoms - specific CSS property that the variable is overriding (background-color, padding, border-radius, etc.)
Below is a comprehensive list of all currently supported CSS variables, along with their names and information regarding the styles they affect (including the default values). They are categorized into different blocks based on the part of the widget they are related to.
General
lc-brand-background-color - represents the color selected on the widget configuration page under Theme. The primary color is used by other CSS variables as the default value (default: the one set on the widget configuration page)
lc-brand-text-color - represents the color selected on the widget configuration page under Theme. The primary text color is used by other CSS variables as the default value (default: the one set on the widget configuration page)
lc-chat-background-color - represents the color selected on the widget configuration page under Theme. The background color is used by other CSS variables as the default value (default: the one set on the widget configuration page)
Header
lc-header-container-height - sets the height of the widget header (default: 80px)
lc-header-container-padding - sets the padding from individual header elements (default: 20px)
lc-header-container-background-color - sets the background color of the widget header (default: lc-brand-background-color)
lc-header-container-border-bottom - sets properties for the bottom border of the widget header (default: none)
lc-header-container-item-gap - sets the gap between header elements (navigation button, title, avatar; default: 10px)
lc-header-thread-list-nav-bar-color - sets the color of the button icon navigating to the thread list in the multi-thread widget (default: lc-brand-text-color)
lc-header-logo-width - sets the width of the widget logo (default: 40px)
lc-header-logo-height - sets the height of the widget logo (default: 40px)
lc-header-logo-margin - sets the margins for the widget logo (default: (0px 0px))
lc-header-logo-border-radius - sets the border radius for the widget logo (default: 50%)
lc-header-title-color - sets the text color of the widget title (default: lc-brand-text-color)
lc-header-title-font-size - sets the font size of the widget title (default: 16px)
lc-header-title-font-weight - sets the font weight of the widget title (default: bold)
lc-header-close-button-visibility - sets the visibility of the Close button if there is one present in the header; by default, it is only shown on mobile-sized screens (default: hidden)
lc-header-close-button-width - sets the width of the Close button (default: 40px)
lc-header-close-button-height - sets the height of the Close button (default: 40px)
lc-header-close-button-color - sets the icon color of the Close button (default: lc-brand-text-color)
Chat
lc-chat-message-bubble-margin - sets the margin around the message bubble (default: (0, 0, 8px, 0))
lc-chat-message-bubble-padding - sets the padding around the message bubble (default: (12px 20px))
lc-chat-message-bubble-text-color - sets the color of the text in the message bubble; it is used for agent/user bubble text color when they are not defined
lc-chat-message-user-bubble-text-color - sets the color of the text in the user message bubble (default: lc-brand-text-color)
lc-chat-message-user-bubble-background-color - sets the background color of the user message bubble (default: lc-brand-background-color)
lc-chat-message-user-bubble-border-radius - sets the border radius of the user message bubble (default: (8px 2px 8px 8px))
lc-chat-message-agent-bubble-text-color - sets the color of the text in the agent message bubble (default: #000)
lc-chat-message-agent-bubble-background-color - sets the background color of the agent message bubble (default: #f7f7f7)
lc-chat-message-agent-bubble-border-radius - sets the border radius of the user message bubble (default: (2px 8px 8px 8px))
Footer
lc-footer-container-background-color - sets the background color of the widget footer (default: lc-chat-background-color)
lc-footer-start-chat-button-background-color - sets the background color of the Start New Chat button used in multi-thread widgets (default: lc-brand-background-color)
lc-footer-start-chat-button-color - sets the text color of the Start New Chat button used in multi-thread widgets (default: lc-brand-text-color)
lc-footer-start-chat-text-color - sets the color of information text explaining why the Start New Chat button is visible, e.g., when a conversation is closed (default: #545454)
lc-footer-attachment-icon-hover-background-color - sets the background color of the attachment button when hovered over (default: #f5f5f5)
lc-footer-attachment-icon-color - sets the color of the attachment icon (default: #B4B4B4)
lc-footer-attachment-icon-selected-color - sets the color of the attachment icon after the user selects an attachment they intend to send (default: lc-brand-background-color)
lc-footer-attachment-background-color - sets the background color of the component representing the attachment ready to be sent by the user (default: lc-brand-background-color)
lc-footer-attachment-color - sets the text color of the component representing an attachment ready to be sent by the user (default: lc-brand-text-color)
lc-footer-send-button-color - sets the color of the Send Message button (default: lc-brand-background-color)
lc-footer-send-button-disabled-color - sets the color of the Send Message button while it is disabled, e.g., when a message input is empty (default: #B4B4B4)
lc-footer-emoji-picker-icon-hover-background-color - sets the background color of the emoji picker button when hovered over (default: #f5f5f5)
lc-footer-emoji-picker-icon-color - sets the color of the emoji picker (default: #B4B4B4)
lc-footer-emoji-picker-icon-selected-color - sets the color of the emoji picker when the emoji picker modal is open (default: lc-brand-background-color)
lc-footer-emoji-picker-color - sets the color of the text in the emoji picker menu (default: #222427)
lc-footer-emoji-picker-border-color - sets the border color of the emoji picker menu (default: #d9d9d9)
lc-footer-emoji-picker-background-color - sets the background color of the emoji picker menu (default: lc-chat-background-color)
lc-footer-emoji-picker-search-color - sets the search text color in the emoji search component (default: lc-footer-emoji-picker-color)
lc-footer-emoji-picker-search-border-color - sets the border color of the emoji search component (default: lc-footer-emoji-picker-border-color)
lc-footer-emoji-picker-search-background-color - sets the background color of the emoji search component (default: lc-footer-emoji-picker-background-color)
lc-footer-emoji-picker-search-icon-color - sets the color of the search icon in the emoji search component (default: lc-footer-emoji-picker-color)
lc-footer-emoji-picker-search-no-result-color - sets the color of the information text displaying that no emoji within the search parameter was found (default: #B4B4B4)
lc-footer-emoji-hover-background-color - sets the background color of the emoji in the picker menu that is currently hovered over(default: #f5f5f5)
Survey
lc-survey-modal-background-color - sets the background color of the survey modal window (default: lc-chat-background-color)
lc-survey-user-rating-item-background-color - sets the background color of the user rating button option (thumbs up, thumbs down) (default: lc-chat-background-color)
lc-survey-user-rating-item-icon-color - sets the color of the icon on the user rating button option (default: lc-brand-background-color)
lc-survey-user-rating-item-selected-background-color - sets the background color of the user rating button option when selected by the user (default: lc-brand-background-color)
lc-survey-user-rating-item-selected-icon-color - sets the color of the icon on the user rating button option when selected by the user (default: lc-brand-text-color)
lc-survey-user-input-background-color - sets the background color of the user feedback input area (default: #f7f7f7)
lc-survey-user-input-placeholder-color - sets the color of the user feedback input placeholder text (default: #545454)
lc-survey-submit-button-background-color - sets the background color of the Submit Survey button (default: lc-brand-background-color)
lc-survey-submit-button-color - sets text color of the Submit Survey button (default: lc-brand-text-color)
lc-survey-submit-button-disabled-background-color - sets the background color of the Submit Survey button when it is disabled (default: #e4e4e4)
lc-survey-submit-button-disabled-color - sets the text color of the Submit Survey button when it is disabled (default: #737376)
Thread list
lc-thread-list-background-color - sets the background color of the thread list view (default: lc-chat-background-color)
lc-thread-list-card-background-color - sets the background color of individual thread cards (default: lc-thread-list-background-color)
lc-thread-list-card-message-info-color - sets the text color of the thread card header and timestamp (default: #545454)
lc-thread-list-card-message-content-color - sets the text color of the thread card message preview (default: #B4B4B4)
Set a theme
To apply the theme to the Live Chat widget on your website, you can use the JS SDK API:
liveChat('set_theme', 'theme_name')
You can call the JS SDK API before initializing the widget, and it will be applied when the widget is rendered on your page. Similarly, calling the API after widget initialization will result in the immediate application of changes. If the API is not called but advanced customization is defined with a default theme, it will automatically apply upon widget initialization.
In case of errors, such as an incorrect JSON structure or calling the API with a non-existent theme, the default values for CSS variables are used, or the previously set theme remains unchanged.