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.

​
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>
Fine-tune the exact offset from screen edges: 
<script
  src="https://widget.illumichat.com/v1/widget.js"
  data-assistant-id="your-assistant-id"
  data-offset-x="24"
  data-offset-y="24"
  async
></script>

​
Suggested Messages

Display clickable message 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-suggested-messages="What does your product do?,How much does it cost?,Can I see a demo?"
  async
></script>
Separate messages with commas. These are displayed as buttons when the chat panel opens.
Keep suggested messages short (under 40 characters each) so they display well on mobile devices. Aim for 3-4 messages.
You can also show suggested messages as floating bubbles near the launcher button: 
<script
  src="https://widget.illumichat.com/v1/widget.js"
  data-assistant-id="your-assistant-id"
  data-suggested-messages="What does your product do?,How much does it cost?"
  data-show-suggested-bubbles="true"
  data-suggested-bubbles-delay="3000"
  async
></script>

​
Auto-Open

Automatically open the chat panel after a delay (in milliseconds): 
<script
  src="https://widget.illumichat.com/v1/widget.js"
  data-assistant-id="your-assistant-id"
  data-auto-open="5000"
  async
></script>
Use auto-open sparingly. A delay of 3 to 10 seconds works well for most use cases.

​
Launcher Icon

Customize the launcher button icon: 
<script
  src="https://widget.illumichat.com/v1/widget.js"
  data-assistant-id="your-assistant-id"
  data-launcher-icon="chat"
  data-company-name="Acme Corp"
  async
></script>

​
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

​
Programmatic Control

For dynamic control, use the JavaScript SDK to interact with the widget at runtime.

​
Control Widget State

// Get the widget instance
const widget = IllumiChat.getInstance();

// Open the widget
widget.open();

// Close the widget
widget.close();

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

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

​
React to Events

const widget = IllumiChat.getInstance();

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

widget.on('message:sent', (data) => {
  console.log('User sent:', data.content);
});

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

​
Full Configuration Reference

AttributeTypeDefaultDescription
data-assistant-idstring—Required. Your assistant ID.
data-primary-colorstring#6366f1Primary brand color (hex).
data-positionstringbottom-rightbottom-right or bottom-left.
data-offset-xstring20Horizontal offset from edge in pixels.
data-offset-ystring20Vertical offset from edge in pixels.
data-auto-openstring—Auto-open delay in milliseconds.
data-suggested-messagesstring—Comma-separated suggested messages.
data-show-suggested-bubblesstringfalseShow message bubbles near launcher.
data-suggested-bubbles-delaystring3000Delay before showing bubbles (ms).
data-launcher-iconstringchatLauncher icon URL or "chat" for default.
data-company-namestringSupportCompany name for accessibility.
data-auth-modestringanonymousanonymous, authenticated, or auto.
data-persist-sessionstringtruePersist session across page loads.
data-visitor-idstring—Custom visitor ID for user linking.
data-base-urlstring—Override widget iframe URL.
data-debugstringfalseEnable debug logging to console.

​
Next Steps

Widget Installation

Install the widget on any website platform

SDK Reference

Complete JavaScript API reference for programmatic control