How to use custom CSS to style web chat

You will learn

How to use custom CSS to change the appearance of Klaviyo web chat — the launcher, the chat window, message bubbles, and the message composer. You'll learn which theme variables and class hooks to use, and how to avoid selectors that may change when Klaviyo updates the interface.

This article applies whether you use web chat on its own or as part of Customer Hub. The chat interface is the same in both cases, so the same CSS works for both.

Before you begin

You'll need:

• An Owner, Admin, or Manager role
• Familiarity with CSS selectors and custom properties (CSS variables)

Before writing custom CSS, check whether the built-in design settings already do what you need. Colors, fonts, button shape, and launcher position are all configurable without code, and those settings survive Klaviyo updates. Reach for custom CSS only for what the design settings don't cover.

To hide the launcher on certain pages of your site, or show it only on certain pages, see How to show or hide the launcher on specific pages.

Where to add your custom CSS

Where you find the Custom CSS editor depends on your setup.

If you use Customer Hub

1. Navigate to Customer Hub > Design, then click Edit your Hub.
2. Select Style in the left sidebar, then scroll to Custom CSS.
3. Click the + button beside Custom CSS and enter your CSS, or edit the CSS already there.
4. Click Save. If a visibility test is running, saving ends it early. Click End test and publish only if you are ready to end the test.

If you use standalone web chat

1. Navigate to Settings > Web chat > Design.
2. Scroll to the Custom section at the bottom of the style settings.
3. Click Add custom CSS and enter your CSS, or edit the CSS already there.
4. Click Save.

After saving, check the chat on your website at desktop and mobile widths. Open and close the launcher, send a message, and check the reply and send button states. To undo a change, remove the affected CSS and save again.

How custom CSS is applied

Your CSS is added to a style tag on your storefront, after Klaviyo's own styles. Two things follow from this:

• Later rules can override earlier rules. Your CSS loads after Klaviyo’s styles, but selector specificity, inline styles, and animations can still take precedence. Use !important only when needed.
• Your CSS is not scoped to the chat. It applies to your whole page. Always scope your selectors to a chat element rather than writing bare rules like button { … }, which would affect your entire storefront.

Start with theme variables

Start by overriding Klaviyo's theme variables in a :root block. This lets you change shared colors and shapes without targeting individual elements. These changes can also affect other parts of Customer Hub. The tables below show base stylesheet defaults; your design settings can override these values.

:root {
  --atlas-chat-bubble-background: #f0ebe4;
  --atlas-message-border-radius: 4px;
}

Chat message variables

Shopper (outgoing) messages intentionally reuse your brand colors: the bubble takes --atlas-button-primary and the text takes --atlas-text-primary-inverse, both of which you set in the design settings.

Color and surface variables

Shape and spacing variables

Typography variables

Several of these are already written from your design settings. Setting fonts and colors in the design settings UI is preferable — use the variables for values the UI doesn't expose.

Target elements with class hooks

When a theme variable won't do, target elements directly. Klaviyo guarantees the class names below.

Chat elements

The chat window also carries a class naming the current screen — .kl-hub-route-chat for the chat itself. In standalone web chat this is always .kl-hub-route-chat. In Customer Hub it changes as the shopper navigates (.kl-hub-route-home, .kl-hub-route-orders, and so on), which lets you scope CSS to one screen.

The send button has no dedicated class. Target it through the composer:

.kl-hub-chat-input-wrapper .kl-hub-button-primary:not(:disabled) {
  --atlas-button-primary: #2f4f4f;
}

Shared elements

Styling agent and shopper messages differently

Human-agent and shopper text messages share the .kl-hub-message class. Customer Agent and automated replies use it too. There is no stable class that selects only one sender type.

Use theme variables to style human agent and shopper bubbles differently. Customer Agent and automated replies have no bubble and use --atlas-text-primary for their text color. Scope the variables to .kl-hub-message to keep these changes within message containers:

.kl-hub-message {
  /* Human-agent messages */
  --atlas-chat-bubble-background: #f0ebe4;
  --atlas-chat-bubble-text-primary: #2b2b2b;

  /* Customer Agent and automated replies */
  --atlas-text-primary: #2b2b2b;

  /* Shopper messages */
  --atlas-button-primary: #1f3a3d;
  --atlas-text-primary-inverse: #ffffff;
}

Examples

Square the chat window, message bubbles, buttons, and inputs

:root {
  --atlas-drawer-inset-border-radius: 0;
  --atlas-message-border-radius: 0;
  --atlas-button-border-radius-normal: 0;
  --atlas-button-border-radius-small: 0;
  --atlas-button-border-radius-tiny: 0;
  --atlas-input-border-radius-normal: 0;
  --atlas-input-border-radius-small: 0;
}

Uppercase headings and buttons

.kl-hub-heading,
.kl-hub-button {
  text-transform: uppercase;
  letter-spacing: 0.04em;
}

Make the launcher larger with a custom shadow

The launcher uses more specific CSS rules and size animations, so this example uses !important. Fixing its width and height also prevents it from expanding for notifications or Add to Cart content. Check those states for clipped content before keeping these size overrides.

.kl-hub-launcher {
  width: 72px !important;
  height: 72px !important;
  box-shadow: 0 12px 32px rgba(0, 0, 0, 0.25) !important;
}

Widen the chat window on desktop

@media (min-width: 900px) {
  .kl-hub-drawer.kl-hub-route-chat {
    width: 480px !important;
  }
}

Troubleshoot custom CSS

In standalone web chat, Klaviyo checks your CSS before saving. If the check fails, you’ll see Invalid CSS. Please check your syntax. and your changes won’t be saved.

This check rejects a nonempty stylesheet when the browser cannot parse any rules. You can clear the field and save to remove your custom CSS. If you see the error, check for:

• Pasting plain text, HTML, or a style tag rather than CSS rules
• Pasting part of a declaration rather than a complete rule
• A stylesheet in which every rule has a syntax error

What custom CSS can't do

• Change text. Custom CSS cannot edit wording. Use the design and content settings for that.
• Reorder or reposition elements beyond what CSS layout allows. The structure of the chat is not customizable.
• Target agent and shopper bubbles separately by class. Use theme variables, as described above.
• Survive redesigns automatically. Class hooks and variables are stable across normal updates, but a significant redesign may require revisiting your CSS. Re-test after major releases.

Additional resources