---
title: Theme Controller
description: A drop-in dark-mode control — no JS wiring, no flash of the wrong theme.
category: Layout
related:
- /components/swap
- /theming
- /components/toggle-button
- /components/dropdown
visibility: guest
draft: false
---
# Theme Controller
Every WireKit app needs a dark-mode toggle, and every one of them hand-rolls the
same three things: the class switch, the persistence, and the head script that
stops the page flashing white before it turns dark.
This is those three things.
:::preview{title="The four control variants"}
:::
Only the last one answers both halves of the question at once — which mode is on, and what it
looks like. Open it and the active row is marked; the trigger changes with it.
:::preview{title="The menu variant, with and without its name"}
:::
## Setup
Two steps, and the first one is not optional.
```blade
{{-- 1. In your layout's , BEFORE any stylesheet.
This applies the reader's stored theme before the first paint. --}}
@wirekitThemeScript
@wirekitStyles
{{-- 2. Put a control wherever it belongs. --}}
```
That is the whole integration. No Alpine store, no `localStorage` plumbing, no
`document.documentElement.classList` in your own code.
::: warning The head script must be inline, and it must come first
`@wirekitThemeScript` is a synchronous inline script on purpose. Anything deferred
or external runs *after* the browser has painted — so the reader sees a white page
that then turns dark. That flash is the whole reason the directive exists, and
moving it below your stylesheet or into your bundle brings it straight back.
If you run a Content Security Policy, pass your nonce: `@wirekitThemeScript($nonce)`.
:::
## Variants
| `variant` | Shape | Use it when |
|-----------|-------|-------------|
| `button` | An icon button that flips light/dark | A header or toolbar (the default) |
| `switch` | A labeled switch | A settings row |
| `select` | System / Light / Dark | A settings row where the reader may say **system** |
| `menu` | A button naming the active mode, with a menu of all three | A header or footer where the reader should SEE which mode is on — and still be able to say **system** |
```blade
```
### Which one names the active mode
Only two of the four can, and only one of those carries an icon:
- `button` shows a glyph and nothing else. A lone sun is **ambiguous** — it may mean the mode
that is on, or the one a click would produce, and those are opposites. It also cannot say
`system`, so the first click leaves that state silently.
- `switch` says which of two. Same missing third state.
- `select` says all three in words. A native `