How to use custom CSS to style web chat

Estimated 5 minute read

|

Updated Sep 2, 2026, 12:00 AM EST

Table of contents

• You will learn
• Before you begin
• Where to add your custom CSS
• How custom CSS is applied
• Start with theme variables
• Target elements with class hooks
• Styling agent and shopper messages differently
• Examples
• Troubleshoot custom CSS
• What custom CSS can't do
• Additional resources

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

Custom CSS is only recommended for technically savvy marketers, or those with access to a developer. Klaviyo's support team can offer general guidance but cannot write or debug custom CSS for you.

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.

If you have Customer Hub enabled, the web chat design settings will point you to Customer Hub instead. This is expected — Customer Hub owns the design for both surfaces, so there's one place to style everything.

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.

cssCopy

: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.

Use class names that start with kl-hub- for custom CSS. The tables below are not an exhaustive list. Avoid generated internal class names, such as Chat-chatWindow-a1B2c, because they can change between releases and cause your CSS to stop matching.

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:

cssCopy

.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:

cssCopy

.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;
}

Setting --atlas-button-primary in :root also changes primary buttons. The example above sets it only on message containers, so primary buttons outside messages keep their design settings. It also affects links within incoming messages.

Examples

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

cssCopy

: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

cssCopy

.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.

cssCopy

.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

cssCopy

@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

A successful save does not guarantee that every rule is valid or matches an element. Browsers can ignore invalid CSS or parse it differently than intended. If a rule has no effect, check the syntax above it as well as the rule itself, especially stray text before selectors and missing braces.

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

• How to style your Customer Hub

Learn about design options for styling your Customer Hub drawer, and how you can design it to match your brand. Because the Customer Hub interface is ingrained in the customer experience, it’s best practice to style it to appear as an extension of your website. - Getting started with web chat

Learn about web chat, which is a 2-way communication channel you can add to your website. Web chat can be set up on its own for you to use with Customer Agent and Helpdesk, but it's also designed to be a seamless part of Customer Hub. Web chat allows your business to engage in live, personalized conversations with visitors on your website so they can easily get answers to their questions or assistance with issues. - Troubleshooting custom CSS, JavaScript, and HTML in Klaviyo

Learn how to troubleshoot custom code when importing a custom HTML template or building your own custom coded template. - How to show or hide the launcher on specific pages

Hide the web chat and Customer Hub launcher on certain pages of your site, or show it only on certain pages, with a short CSS snippet in your site theme.

Was this article helpful?

YesNo

Use this form only for article feedback. Learn how to contact support.

Explore more from Klaviyo

Community

Connect with peers, partners, and Klaviyo experts to find inspiration, share insights, and get answers to all of your questions.

Visit Community

Partners

Hire a Klaviyo-certified expert to help you with a specific task, or for ongoing marketing management.

Hire a partner

Support

Access support through your account.

Email support (free trial and paid accounts) Available 24/7

Chat/virtual assistance Availability varies by location and plan type

Log in