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 names are safe to target, and which ones will break when Klaviyo ships an update.

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.

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.
2. Scroll to the Custom section at the bottom of the style settings.
3. Click Add custom CSS, or edit the CSS already there.
4. Click Save.

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, or edit the CSS already there.
4. Click Save.

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:

• Your CSS wins. Because it loads last, your rules override Klaviyo's defaults without needing !important in most cases.
• 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

The most reliable way to restyle web chat is to override Klaviyo's theme variables in a :root block. These are stable, they cascade correctly through the whole interface, and they're much less likely to break than targeting individual elements.

: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 {
  background: #2f4f4f;
}

Shared elements

Styling agent and shopper messages differently

This is the most common request, and it needs a specific approach. Agent and shopper bubbles share the single .kl-hub-message class — there is no stable class distinguishing them, so you cannot select one directly.

Instead, use the theme variables, which already treat the two differently:

:root {
  /* Agent messages */
  --atlas-chat-bubble-background: #f0ebe4;
  --atlas-chat-bubble-text-primary: #2b2b2b;

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

Examples

Square everything off

:root {
  --atlas-drawer-inset-border-radius: 0;
  --atlas-message-border-radius: 0;
  --atlas-button-border-radius: 0;
  --atlas-input-border-radius-normal: 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

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

The launcher sets several properties directly on the element, so launcher rules need !important to take effect. This is the one place it's routinely required.

Widen the chat window on desktop

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

If your CSS won't save

When you save, Klaviyo checks that your CSS parses. If it doesn't, you'll see Invalid CSS. Please check your syntax. and your changes won't be saved.

A stylesheet is only rejected outright when it produces no rules at all, which usually means what you pasted isn't CSS. Common causes:

• 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