> For the complete documentation index, see [llms.txt](https://docs.enable3.io/enable3/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.enable3.io/enable3/getting-started/basic-setup/custom-theme-switching.md).

# Custom Theme Switching

### **Custom Theme Switching**

Below is a guide on how to set and switch the widget theme using the methods available on the `window.fncWidget` object.

#### `themeLoaded(callback)`

Fires when the widget is ready to accept theme colors.\
On the initial widget load, `changeTheme` should be called only inside this callback (or after it).

**Parameters:**

* `callback: Function` — a function that will be called when the widget is ready.

#### `changeTheme(colors)`

Applies the provided color palette.

**Parameters:**

* `colors: string[]` — an **array of 8 colors** in a fixed order (HEX, or named colors).

**Color order (**`colors[index]`**):**

1. `main-color`
2. `text-color`
3. `text-color-button`
4. `theme-background-color`
5. `theme-block-background-color`
6. `theme-block-inner-background-color`
7. `gradient-color-1`
8. `gradient-color-2`

### **Example:**  **Setting a custom theme on page load**

Call `themeLoaded` after `DOMContentLoaded` and inside it — `changeTheme` with your palette:

```javascript
<script>
document.addEventListener('DOMContentLoaded', function () {
  window.fncWidget.themeLoaded(function () {
    window.fncWidget.changeTheme([
      '#6352ff', // main-color
      '#34414d', // text-color
      '#ffffff', // text-color-button
      '#f6f6f6', // theme-background-color
      '#ffffff', // theme-block-background-color
      '#dddddd', // theme-block-inner-background-color
      '#317cff', // gradient-color-1
      '#8f4eff'  // gradient-color-2
    ]);
  });
});
</script>
```

#### Manual theme switching (e.g., via buttons)

```javascript
<script>
function applyLightTheme() {
  window.fncWidget.changeTheme([
    '#6352ff', // main-color
    '#34414d', // text-color
    '#ffffff', // text-color-button
    '#f6f6f6', // theme-background-color
    '#ffffff', // theme-block-background-color
    '#dddddd', // theme-block-inner-background-color
    '#317cff', // gradient-color-1
    '#8f4eff'  // gradient-color-2
  ]);
}

function applyDarkTheme() {
  window.fncWidget.changeTheme([
    '#8f4eff', // main-color
    '#e6ecf1', // text-color
    '#0b0f13', // text-color-button
    '#12171c', // theme-background-color
    '#1b2127', // theme-block-background-color
    '#2a323a', // theme-block-inner-background-color
    '#7fb0ff', // gradient-color-1
    '#b28cff' // gradient-color-2
  ]);
}
</script>
```

### **Recommendations & Notes**

* **Call** `changeTheme` **only after the widget is ready** — inside `themeLoaded` or later (e.g., on user interaction).
* **Color format**: HEX (`#rrggbb` / `#rgb`) is preferred.
* **Idempotent**: Multiple calls to `changeTheme` will simply re-render the theme without reloading the widget.
* **Validation**: If possible, validate color values before calling `changeTheme`.

### **Common use case**

**Syncing with the site theme**\
If your site already has a light/dark mode switcher, call the corresponding function (`applyLightTheme`/`applyDarkTheme`) on theme change. Ensure the widget is “ready” before the first call (via `themeLoaded`).