Skip to main content

​
Overview

The IllumiChat widget can be customized to match your website’s branding and design. This guide covers visual customization through data-* attributes, CSS overrides, and programmatic control via the SDK.

​
Theme

The widget supports three theme modes:
ThemeDescription
lightLight background with dark text. Best for light-themed websites.
darkDark background with light text. Best for dark-themed websites.
autoFollows the user’s system preference (prefers-color-scheme).
<script
  src="https://widget.illumichat.com/v1/widget.js"
  data-assistant-id="your-assistant-id"
  data-theme="dark"
  async
></script>

​
Colors

Set the primary color using the data-primary-color attribute. This color is applied to the launcher button, message bubbles, and interactive elements. 
<script
  src="https://widget.illumichat.com/v1/widget.js"
  data-assistant-id="your-assistant-id"
  data-primary-color="#6366F1"
  async
></script>
Color ValueResult
#6366F1Indigo (default)
#10B981Green
#F59E0BAmber
#EF4444Red
Any hex codeYour brand color
Choose a color with sufficient contrast against both light and dark backgrounds. The widget automatically adjusts text color for readability.

​
Position

Control where the widget launcher appears on the page. 
<script
  src="https://widget.illumichat.com/v1/widget.js"
  data-assistant-id="your-assistant-id"
  data-position="bottom-right"
  async
></script>

​
Greeting Message

Set a custom greeting that appears when the widget opens for the first time. 
<script
  src="https://widget.illumichat.com/v1/widget.js"
  data-assistant-id="your-assistant-id"
  data-greeting="Hi there! How can we help you today?"
  async
></script>
If no greeting is set, the widget uses the assistant’s welcomeMessage from its configuration.

​
Suggested Questions

Display clickable question chips that visitors can tap to start a conversation quickly. 
<script
  src="https://widget.illumichat.com/v1/widget.js"
  data-assistant-id="your-assistant-id"
  data-suggestions="What does your product do?,How much does it cost?,Can I see a demo?"
  async
></script>
Separate questions with commas. These are displayed as buttons below the greeting message.
Keep suggested questions short (under 40 characters each) so they display well on mobile devices. Aim for 3-4 questions.

​
Custom CSS

For advanced styling, you can target the widget’s shadow DOM elements using CSS custom properties (CSS variables). 
<style>
  illumichat-widget {
    --ic-font-family: 'Inter', system-ui, sans-serif;
    --ic-border-radius: 12px;
    --ic-launcher-size: 56px;
    --ic-launcher-margin: 20px;
  }
</style>
CSS VariableDefaultDescription
--ic-font-familysystem-uiFont family for all widget text
--ic-border-radius16pxBorder radius for the chat window
--ic-launcher-size56pxSize of the floating launcher button
--ic-launcher-margin16pxDistance from screen edges
The widget uses Shadow DOM for style isolation. Standard CSS selectors will not affect widget internals. Use the CSS custom properties listed above for supported customizations.

​
Mobile Behavior

The widget automatically adapts to mobile screens:
  • On screens narrower than 480px, the chat window expands to full width
  • The launcher button is slightly smaller on mobile (48px vs 56px)
  • Touch-friendly tap targets and scrolling are enabled
You can disable the widget on mobile entirely: 
<script
  src="https://widget.illumichat.com/v1/widget.js"
  data-assistant-id="your-assistant-id"
  data-hide-on-mobile="true"
  async
></script>

​
Programmatic Customization with the SDK

For dynamic control, use the JavaScript SDK to update widget settings at runtime.

​
Update Configuration

// Change the primary color based on the page
IllumiChat.updateConfig({
  primaryColor: '#10B981',
  greeting: 'Welcome to our pricing page! Any questions about our plans?',
});

​
Control Widget State

// Open the widget
IllumiChat.open();

// Close the widget
IllumiChat.close();

// Toggle open/close
IllumiChat.toggle();

// Send a pre-filled message
IllumiChat.sendMessage('I want to learn about enterprise pricing');

​
React to Events

// Listen for widget events
IllumiChat.on('open', () => {
  console.log('Widget opened');
});

IllumiChat.on('message', (data) => {
  console.log('New message:', data);
});

IllumiChat.on('lead-captured', (data) => {
  // Track conversion in analytics
  gtag('event', 'lead_captured', {
    email: data.email,
    source: 'widget',
  });
});
See the SDK Reference for the complete list of methods and events.

​
Page-Specific Customization

You can show different widget configurations on different pages: 
<script>
  // Detect the current page and customize the widget
  const config = {
    '/pricing': {
      greeting: 'Questions about pricing? I can help!',
      suggestions: 'Compare plans,Free trial details,Enterprise pricing',
    },
    '/docs': {
      greeting: 'Need help with our documentation?',
      suggestions: 'Getting started,API reference,Troubleshooting',
    },
  };

  const pageConfig = config[window.location.pathname] || {};
</script>
<script
  src="https://widget.illumichat.com/v1/widget.js"
  data-assistant-id="your-assistant-id"
  async
></script>
<script>
  // Apply page-specific config after widget loads
  if (window.IllumiChat && pageConfig.greeting) {
    IllumiChat.updateConfig(pageConfig);
  }
</script>

​
Full Configuration Reference

AttributeTypeDefaultDescription
data-assistant-idstring—Required. Your assistant ID.
data-primary-colorstring#6366F1Primary brand color (hex).
data-themestringlightlight, dark, or auto.
data-positionstringbottom-rightbottom-right or bottom-left.
data-greetingstring—Custom greeting message.
data-suggestionsstring—Comma-separated suggested questions.
data-hide-on-mobilestringfalseHide widget on mobile devices.
data-open-on-loadstringfalseAuto-open widget on page load.
data-auth-modestringanonymousanonymous, authenticated, or auto.

​
Next Steps

Widget Installation

Install the widget on any website platform

SDK Reference

Complete JavaScript API reference for programmatic control