Custom CSS

Add your own custom CSS styling to fully customize your chat widget's appearance beyond the built-in customization options.

Overview

The custom CSS feature allows you to inject your own CSS styles directly into the chat widget, giving you complete control over its appearance. This is perfect for:

• Matching your brand's exact design system
• Adding animations and transitions
• Fine-tuning spacing and typography
• Creating unique visual effects
• Overriding default styles for specific elements

There are two ways to add custom CSS:

• Option 1 (recommended): Use the dashboard editor — write once, preview live, and your CSS is auto-synced to your embed code.
• Option 2 (legacy): Add theme.customCSS directly in your embed script — only if you are still following the previous manual workflow.

Option 1 — Dashboard (Recommended)

This is the easiest and recommended way to add custom CSS. CSS you write here is saved with your widget and automatically injected into your embed code when you copy or install the widget — no duplicate work in your HTML or JavaScript.

How to add custom CSS in the dashboard

1. Open your widget in the dashboard.
2. Go to Customize → Advanced.
3. Write your CSS in the Custom CSS editor.
4. Preview changes in real time as you type.
5. Save your widget — your CSS is persisted and included in the embed code automatically.

You never need to touch theme.customCSS in your embed script unless you have a specific reason to use the legacy method described in Option 2.

Example CSS (also available via Insert Sample in the editor):

.n8n-chat-ui-bot-message {
  font-family: "Courier New", Courier, monospace !important;
  font-weight: 900 !important;
  background-color: blueviolet !important;
}

Tips

• Use browser inspection tools to target elements inside the chat widget — all styles are reflected in real time as you type.
• Always use !important in your styles to ensure they override default widget styles.
• Prefer the dashboard editor so your CSS stays in sync with your embed code.

Option 2 — Manual embed code (Legacy method)

Before the dashboard editor existed, custom CSS was added by setting theme.customCSS directly inside your embed script. If you are starting fresh, use Option 1 instead — it saves your CSS and includes it in embed code automatically. This section is for users who are still following the previous embed-code workflow.

When you might still use this

• You already have CSS hardcoded in embed scripts across multiple sites and have not migrated yet.
• You intentionally manage CSS in source control outside the dashboard.

Managed / hosted widgets

Pass theme.customCSS inside n8nChatUiWidget.load():

<script type="module" defer>
  import n8nChatUiWidget from "https://proxy.n8nchatui.com/api/embed/YOUR_WIDGET_SLUG";
 
  n8nChatUiWidget.load({
    theme: {
      customCSS: `.n8n-chat-ui-bot-message {
  font-family: "Courier New", Courier, monospace !important;
  font-weight: 900 !important;
}`,
    },
  });
</script>

For multi-line styles, use template literals with backticks for better readability:

<script type="module" defer>
  import n8nChatUiWidget from "https://proxy.n8nchatui.com/api/embed/YOUR_WIDGET_SLUG";
 
  n8nChatUiWidget.load({
    theme: {
      customCSS: `
        .n8n-chat-ui-bot-container {
          background-color: #f9f9f9 !important;
          border-radius: 10px !important;
        }
 
        .n8n-chat-ui-bot-message {
          font-family: "Courier New", Courier, monospace !important;
          font-weight: 900 !important;
        }
      `,
    },
  });
</script>

Standalone widgets

For most users, CSS added in the dashboard is already included in the generated embed theme object — no manual step is needed.

The legacy manual method is to edit your embed script and set theme.customCSS inside Chatbot.init() or Chatbot.initFull():

<script type="module" defer>
  import Chatbot from "https://cdn.n8nchatui.com/v1/embed.js";
 
  Chatbot.init({
    n8nChatUrl: "YOUR_N8N_CHAT_TRIGGER_NODE_WEBHOOK_URL",
    theme: {
      customCSS:
        ".n8n-chat-ui-bot-container { background-color: red !important; }",
    },
  });
</script>

Best Practices

Always Use !important

We recommend adding !important to all your custom CSS rules to ensure they override the default widget styles:

.n8n-chat-ui-bot-container {
  background-color: red !important;
  padding: 20px !important;
  border-radius: 10px !important;
}

This ensures your custom styles take precedence over the widget's default styling, preventing conflicts and ensuring consistent appearance.

Use Specific Selectors

Always use the provided CSS class names to ensure your styles target the correct elements:

/* Good - specific selector with !important */
.n8n-chat-ui-bot-message {
  background-color: #f0f0f0 !important;
}
 
/* Avoid - too generic */
.message {
  background-color: #f0f0f0;
}

Troubleshooting

Styles Not Applying?

• Try adding !important to override default styles
• Check if you're using the correct CSS selectors
• Verify your CSS syntax is correct
• Make sure you are using a managed widget with credits, or a standalone widget with a standalone license
• If CSS works in the dashboard preview but not on your site, check whether legacy theme.customCSS in your embed script is overriding dashboard CSS

Premium Upgrade

Custom CSS is a premium feature for standalone widgets and is included with managed widgets. If you haven't upgraded yet, visit our pricing page to unlock this and other advanced customization options.

Next Steps

• Add CSS in the dashboard under Customize → Advanced for the simplest workflow
• Explore Widget API Reference for more customization options
• Learn about Metadata Configuration for enhanced functionality