# Dark Mode Toggle

A front-end light/dark switch that recolours your site by overriding Elementor's global colours.

Found in the Elementor panel under **Dotjuice → Dark Mode Toggle**.

![The Dark Mode Toggle widget controls in the Elementor panel](../assets/img/dark-mode-toggle-controls.png)
*Screenshot: the widget selected in the editor with the **Icons** section open, showing the Normal/Dark icon pickers and colour controls.*

## How it works

The widget renders a small clickable icon. Clicking it adds a dark-mode class to your entire site and swaps your global colours for the dark-mode values you configure on the widget. The choice is stored in the visitor's browser, so it survives navigation and returns on their next visit.

It works with **both** of Elementor's global-colour systems:

- **Legacy 3.x global colours** — the four classic Global Colors (Primary, Secondary, Text, Accent) used by traditional Elementor widgets.
- **Elementor 4.x global variables** — the named colour variables (e.g. `red`, `sea-green`) introduced with the newer atomic widgets, defined under **Site Settings → Global Variables**.

Modern pages commonly mix older widgets (which read the legacy colours) with newer atomic widgets (which read 4.x variables), so the widget can override both at once from a single toggle.

:::caution The single most important thing to understand
Dark mode only changes elements styled with a **global colour or global variable**. Anything using a hardcoded hex value won't respond at all. If your toggle seems to "only half work", that's almost always the cause — the more consistently your design uses globals, the more complete the effect.
:::

## Content settings — Icons

| Setting | Default | What it does |
|---|---|---|
| **Normal Mode Icon** | Moon | Shown while the site is in light mode. Clicking it switches to dark. |
| **Dark Mode Icon** | Sun | Shown while the site is in dark mode. Clicking it switches back to light. |
| **Icon Color** | — | Colour of the toggle icon itself (not affected by dark mode). |
| **Hover Color** | — | Icon colour on hover. |
| **Icon Size** | 24px | Responsive — set a different size per breakpoint if needed. |

## Dark Mode Colors

**Global Colour System** decides which colour systems the toggle overrides:

| Choice | What it does |
|---|---|
| **Both** *(default)* | Applies the legacy four colours **and** your 4.x variable overrides together. Best for pages mixing old and new widgets. |
| **Legacy only — Elementor 3.x** | Overrides just Primary, Secondary, Text and Accent. |
| **Variables only — Elementor 4.x** | Overrides just the global variables, leaving the classic four untouched. |

**Legacy 3.x global colors** — four colour fields (**Primary**, **Secondary**, **Text**, **Accent**) define the dark equivalent of each classic Global Color. Leave any blank to fall back to a sensible built-in dark default.

**Elementor 4.x global variables** — a repeater. Add one row per variable you want to change: pick the variable from your site's list, then set its dark-mode colour. Add as many rows as you need; variables you don't list keep their normal values.

![The Dark Mode Colors section with variable override rows](../assets/img/dark-mode-toggle-colours.png)
*Screenshot: the **Dark Mode Colors** section showing the Global Colour System dropdown, the four legacy colour fields, and two or three variable override rows.*

:::note
New variables created *after* you opened the editor won't appear in the dropdown until you reload it — Elementor builds the widget's option list once, when the editor loads.
:::

## Setting it up

1. Add the widget somewhere reachable from every page — a header or footer is the usual choice.
2. Choose your **Global Colour System**. Leave it on **Both** unless you know your site uses only one widget generation.
3. Set the legacy dark colours, and/or add a variable row for each global variable that needs a dark value.
4. Save, then click the toggle on the live site and check that everything using globals switches cleanly.

## Good to know

- **The most recently clicked toggle determines the colours used site-wide.** If you place several toggles with different settings, the last one clicked wins until another is clicked. For consistency, either use identical settings everywhere or place a single toggle in a shared header.
- **Changed your colours after already switching dark mode on?** Toggle it off and on once, or clear the browser's site data. The last-used colours are cached in the browser for speed, so a stale set can linger.
- **You can deep-link into dark mode** by adding `?dark=0` to any URL — or `?dark=1`, `?dark=2` and so on where a page holds more than one toggle. Handy for sharing a dark-mode preview.
- **The preference is per browser, not per WordPress account.** It persists across visits on the same device but doesn't follow a visitor to another device or browser.