> ## Documentation Index
> Fetch the complete documentation index at: https://docs.illumichat.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Widget Customization

> Customize your IllumiChat widget's appearance, behavior, and branding to match your website.

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

```html theme={null}
<script
  src="https://widget.illumichat.com/v1/widget.js"
  data-assistant-id="your-assistant-id"
  data-primary-color="#6366F1"
  async
></script>
```

| Color Value  | Result           |
| ------------ | ---------------- |
| `#6366F1`    | Indigo (default) |
| `#10B981`    | Green            |
| `#F59E0B`    | Amber            |
| `#EF4444`    | Red              |
| Any hex code | Your brand color |

<Tip>
  Choose a color with sufficient contrast against both light and dark backgrounds. The widget automatically adjusts text color for readability.
</Tip>

## Position

Control where the widget launcher appears on the page.

<CodeGroup>
  ```html Bottom Right (Default) theme={null}
  <script
    src="https://widget.illumichat.com/v1/widget.js"
    data-assistant-id="your-assistant-id"
    data-position="bottom-right"
    async
  ></script>
  ```

  ```html Bottom Left theme={null}
  <script
    src="https://widget.illumichat.com/v1/widget.js"
    data-assistant-id="your-assistant-id"
    data-position="bottom-left"
    async
  ></script>
  ```
</CodeGroup>

Fine-tune the exact offset from screen edges:

```html theme={null}
<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.

```html theme={null}
<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.

<Note>
  Keep suggested messages short (under 40 characters each) so they display well on mobile devices. Aim for 3-4 messages.
</Note>

You can also show suggested messages as floating bubbles near the launcher button:

```html theme={null}
<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>
```

<Note>
  The easiest way to enable these bubbles is the dashboard: **Widget → Styles →
  Popup messages** lets you set up to 3 dedicated teaser messages and a delay,
  with no embed changes needed. When popup messages are configured there, the
  bubbles show those instead of your suggested messages, and clicking a bubble
  opens the chat. Script-tag attributes still take priority over dashboard
  settings. See [Popup Messages](/widget/configuration#popup-messages).
</Note>

## Auto-Open

Automatically open the chat panel after a delay (in milliseconds):

```html theme={null}
<script
  src="https://widget.illumichat.com/v1/widget.js"
  data-assistant-id="your-assistant-id"
  data-auto-open="5000"
  async
></script>
```

<Tip>
  Use auto-open sparingly. A delay of 3 to 10 seconds works well for most use cases.
</Tip>

## Launcher Icon

Customize the launcher button icon:

```html theme={null}
<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).

```html theme={null}
<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 Variable           | Default     | Description                          |
| ---------------------- | ----------- | ------------------------------------ |
| `--ic-font-family`     | `system-ui` | Font family for all widget text      |
| `--ic-border-radius`   | `16px`      | Border radius for the chat window    |
| `--ic-launcher-size`   | `56px`      | Size of the floating launcher button |
| `--ic-launcher-margin` | `16px`      | Distance from screen edges           |

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

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

```javascript theme={null}
// 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

```javascript theme={null}
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](/widget/sdk-reference) for the complete list of methods and events.

## Full Configuration Reference

| Attribute                      | Type   | Default        | Description                                |
| ------------------------------ | ------ | -------------- | ------------------------------------------ |
| `data-assistant-id`            | string | --             | Required. Your assistant ID.               |
| `data-primary-color`           | string | `#6366f1`      | Primary brand color (hex).                 |
| `data-position`                | string | `bottom-right` | `bottom-right` or `bottom-left`.           |
| `data-offset-x`                | string | `20`           | Horizontal offset from edge in pixels.     |
| `data-offset-y`                | string | `20`           | Vertical offset from edge in pixels.       |
| `data-auto-open`               | string | --             | Auto-open delay in milliseconds.           |
| `data-suggested-messages`      | string | --             | Comma-separated suggested messages.        |
| `data-show-suggested-bubbles`  | string | `false`        | Show message bubbles near launcher.        |
| `data-suggested-bubbles-delay` | string | `3000`         | Delay before showing bubbles (ms).         |
| `data-launcher-icon`           | string | `chat`         | Launcher icon URL or `"chat"` for default. |
| `data-company-name`            | string | `Support`      | Company name for accessibility.            |
| `data-auth-mode`               | string | `anonymous`    | `anonymous`, `authenticated`, or `auto`.   |
| `data-persist-session`         | string | `true`         | Persist session across page loads.         |
| `data-visitor-id`              | string | --             | Custom visitor ID for user linking.        |
| `data-base-url`                | string | --             | Override widget iframe URL.                |
| `data-debug`                   | string | `false`        | Enable debug logging to console.           |

## Next Steps

<CardGroup cols={2}>
  <Card title="Widget Installation" icon="download" href="/widget/installation">
    Install the widget on any website platform
  </Card>

  <Card title="SDK Reference" icon="code" href="/widget/sdk-reference">
    Complete JavaScript API reference for programmatic control
  </Card>
</CardGroup>