Introduction

Hello! 👋

This documentation will get you started with creating custom LiveChat themes (skins).

Chat window structure

The LiveChat widget is an iframe wrapped in a div. The basic structure of a maximized window looks like this:

The widget consists of the following elements:

Minimized chat window

This item is placed in #livechat-compact-container element.

Maximized chat window

This item is placed in #livechat-full element.

The chat window is situated in #wrapper element. The window itself is an HTML table element (#content).

The default chat window is built of the following parts:

Title bar

This item is placed in #title-container element. It contains the chat title and the icons that change depending on the chat state.

Agent bar

This item is placed in #operators element. It displays the details of the current agent, rating buttons, email transcript buttons and the company logo (if provided).

Chat body

This item is placed in #body-container element. It displays the current chat view. The possible elements are:

  • #view-loading - it is displayed e.g. when a visitor is waiting for the chat to start.
  • #view-offline-message-sent it is displayed when the ticket form has been sent successfully.
  • #view-connection-lost - it is displayed when a visitor is disconnected from the chat.
  • #view-not-working-cookies-and-local-storage - it is displayed when visitor’s device doesn’t support cookies.
  • #view-confirm-closing - it is displayed when a visitor has clicked “Close” button to end the chat.
  • #view-prechat-survey - it displays the pre-chat survey.
  • #view-chat - it displays the actual chat flow.
  • #view-postchat-survey - it displays the post-chat form.
  • #view-offline-form - it displays the ticket form (shown when there is no agent available)
  • #view-queued-form - it displays the queue form (shown when the visitor is waiting in a queue)
  • #view-information - it displays system info.

Visitor area

This is where chat visitors type in their messages.

This item is placed in #textarea element. It contains a text input and “File upload” button. On mobile devices there is also “Send” button.

After-greeting button

This item is placed in #survey-after-greeting element. It is displayed when “Show prechat survey after greeting” option is enabled and when a visitor has received a greeting.

This item is placed in #footer element. It displays “Powered by LiveChat” message and social media buttons (if provided).

Badge

The badge displays the number of new messages from chat operator.

This item is placed in #livechat-badge element.

Eye-catcher container

This item is placed in #livechat-eye-catcher element.

Chat window theme

A theme is basically a set of CSS rules applied to the elements of the chat window.

The styles are injected to #livechat-full and #livechat-compact-container.

Additionally, you can apply styles to these containers themselves to change their size or position:

#livechat-full {
    width: 500px;
    height: 890px;
}

Creating a theme

To create a custom theme, you have to modify one of the default skins: Classic, Modern, Minimal or Circle.

The easiest way to do this is to use “Customize using own CSS” option in the Agent App (Chat Window > Theme). There is a live preview available, so you can immediately see your changes.

Keep in mind that your custom theme will support only the elements available in your base theme (i.e. the default skin that you’re modifying). For example, Minimal theme doesn’t support chat rating and transcripts, so these won’t be visible in your custom theme.

Additional classes

The <body> element in the widget iframe gets additional classes in the following cases:

  • state-chatting - when a visitor is chatting
  • avatar-enabled - when agent avatar is enabled
  • chat-ended - when the chat has ended
  • has-operators-bar - when the agent bar is visible
  • email-transcript-form-visible - when the transcript form is displayed
  • rate-comment-form-visible - when the rating form is displayed

You can use them to style the chat window depending on the chat state. For example, you can add a semi-transparent overlay to the chat window when the transcript form is visible:

Additional CSS functions

Mobile styles

There is no support for media-queries in the custom CSS, but you can decide which styles will work only on mobile devices. To do this, wrap the mobile-only styles in @livechat-mobile. For example, to give the #wrapper a red border on desktop and green border on mobile, do this:

#wrapper {
    border: 1px solid red;
    box-shadow: 1px 1px 1px #000;
}
@livechat-mobile {
    #wrapper {
        border: 1px solid green;
    }
}

Note that box-shadow property is not overwritten in the mobile styles, so the mobile styles will inherit it.

Variables

You can use %color% variable in your custom CSS. It will pick up the selected visitor color:

Additional options

Icons color

The icons in the chat window are actually a font, so you can easily change their color:

.icon-close {
    color: red;
}

Custom fonts

You can use custom fonts in your chat widget. See LiveChat Custom Fonts for details.

Final notes

When creating a custom theme, keep the following in mind:

Right-to-left support

If a RTL language is enabled, the <body> element receives rtl-lang class. Make sure that the interface is displayed correctly in the RTL mode.

Mobile devices

Always check if your theme works correctly on mobile devices. LiveChat adds some default styles that improve the usability of the mobile window.

Visitor color

Using %color% variable in your custom CSS will make the theme more flexible - there will be no need to change the color manually in the code.

Advanced properties

There are three options in “Advanced window tweaks” available:

  • Display logo
  • Display agent’s picture
  • Display mobile icon when agent is using a mobile device

Make sure that your theme works correctly whether or not these are enabled.

Social media

There is an option to add social media icons in the chat window footer. Check if your theme displays them correctly.

Minimized window options

There are two types of the minimized window to choose from: bar and bubble. Test your theme with both!

Flexibility

Make sure that long texts (e.g. chat title, agent name and title, chat messages) are displayed properly in your theme.

Control inputs

LiveChat window supports text inputs, radio buttons and checkbox. Provide styles for all of them.

Chat window options

There are two types of LiveChat window:

  • embedded
  • pop-up

Additionally, there is a full-screen window (upon clicking direct chat link).

Test your theme for all window types.

Cross-browser compatibility

We recommend that you test your theme in the most popular browsers (the latest versions of Chome, Firefox, Safari and IE) for maximum compatibility.

Sample themes

We have created a set of sample skins to demonstrate the structure of a custom theme. They can be found on GitHub here.

Publish a theme

To publish a theme in the LiveChat Marketplace, you will need an account in the Developers Console. If you don’t have it yet, create it here.

Create a new theme

To set up a new theme in the Console, go to Apps and hit “New app”. Select “Chat widget theme (just CSS)” type.

Add custom styles

The first screen you will see after creating an app is “Features”. This is where you select the base theme for your custom skin and paste your CSS code.

Set up display options

When you move to “Display” screen, you will be able to add an icon and descriptions for your theme.

Distribute

Finally, you can go to “Distribution” screen to install the theme for your license or submit it for review.

Edit a theme

To edit a published theme, you need to clone it. The copy, once reviewed and accepted, will overwrite the old version in the Marketplace. It will also automatically replace the old version of the theme for all users.

To clone a theme, go to its “Overview” screen and click “Clone this app” button.

Then proceed like normal: modify the code in “Features” section and submit the theme for review in “Distribution” screen.