# Dark Mode Toggle

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

## How it works

This widget renders a small clickable icon. Clicking it adds a dark-mode class to your entire site and swaps your global colours to the dark-mode values you configure on the widget. It remembers the visitor's choice, so it stays applied 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/v4 widgets, defined under **Site Settings → Global Variables**.

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

**Important:** this widget only changes colours for elements styled using a global colour or global variable. Anything using a hardcoded colour won't respond to dark mode — the more consistently your design uses global colours/variables, the more complete the effect.

## Content settings

| Setting | Default | What it does |
|---|---|---|
| **Light Mode Icon** | Moon icon | The icon shown when the site is currently in light mode (click to switch to dark). |
| **Dark Mode Icon** | Sun icon | The icon shown when the site is currently in dark mode (click to switch back to light). |
| **Icon Color / Hover Color** | — | Styling for the toggle icon itself. |
| **Icon Size** | — | Responsive sizing for the toggle icon. |

## Dark Mode Colors (Style tab)

At the top, **Global Colour System** decides which colour systems dark mode overrides:

| Choice | What it does |
|---|---|
| **Both** *(default)* | Applies the legacy four colours **and** your chosen 4.x variable overrides together — best for pages that mix old and new widgets. |
| **Legacy only** | Overrides just the four classic Global Colors. |
| **Variables only** | Overrides just the 4.x global variables, leaving the legacy 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 use a sensible built-in dark default.

**Elementor 4.x global variables** — add a row for each variable you want to change in dark mode: pick the variable from the list of your site's global variables, then set its dark-mode colour. The dark value can be a plain colour, or a reference to one of your palette colours. Add as many rows as you need.

> New variables you create *after* opening the editor won't appear in the list until you reload the editor, because Elementor builds the widget's options once when the editor loads.

## Setting it up

1. Add the widget somewhere visible and consistent — a header or footer works well, so it's reachable from every page.
2. Under the Style tab, choose your **Global Colour System** (leave on **Both** if your site mixes widget types).
3. Set your Legacy dark colours and/or add variable rows for a palette that works well as a dark theme.
4. Save and test: click the toggle on the live site and confirm the elements using your global colours/variables switch correctly.

## Good to know

- **Whichever toggle instance was clicked most recently determines the colours used site-wide.** If you place more than one Dark Mode Toggle with different settings, the last one clicked "wins" for the whole site until another is clicked. For a single consistent dark mode, use the same settings on every instance, or place the widget in one shared location like your header.
- If you change the widget's colour settings after already switching dark mode on, toggle it off and back on once (or clear the browser's site data) so it re-reads the new values — the last-used colours are cached in the browser for speed.
- You can deep-link directly into dark mode by adding `?dark=0` to any URL (or `?dark=1`, `?dark=2`, etc. if there's more than one toggle instance on that specific page) — useful for sharing a dark-mode preview link.
- The dark mode choice is remembered per browser (not per WordPress account), so it persists across visits on the same device but doesn't follow a visitor between devices.