# Add a Dark Mode Toggle to a Leptos App

Yes. An agent adds a dark mode toggle to your Leptos app that follows the system theme, keeps the choice across reloads with no flash, and opens a PR with a test.

[Run this on Rush](https://cloud.getrush.ai/run/add-dark-mode/leptos/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads how the app renders before it touches a stylesheet, because dark mode in a server-rendered Leptos app is mostly a question of what the browser sees before hydration. In a project generated from leptos-rs/start-axum, `Cargo.toml` pins `leptos`, `leptos_router` and `leptos_meta` at 0.8 with `axum` and `leptos_axum` behind the `ssr` feature and `wasm-bindgen` behind `hydrate`; `[package.metadata.leptos]` points `style-file` at `style/main.scss`, `assets-dir` at `public` and `site-addr` at `127.0.0.1:3000`. `src/app.rs` has a `shell` function that writes the `<html>` and `<head>` with `AutoReload`, `HydrationScripts` and `MetaTags`, and an `App` component that calls `provide_meta_context`, adds a `Stylesheet` and `Title`, and routes `/` to a `HomePage` with a counter button. `style/main.scss` sets a sans-serif font and centred text and nothing else.

The theme lives in three places. In `style/main.scss` the agent defines CSS custom properties on `:root` for background, text and the button, a `@media (prefers-color-scheme: dark)` block that flips them, and `html.dark` and `html.light` rules that override the media query when the visitor has chosen. In `src/app.rs` it adds a `Theme` enum (`System`, `Light`, `Dark`), an `RwSignal<Theme>` provided through context in `App`, and a `ThemeToggle` component rendered in the `<main>` above the routes that cycles the value. The class on the document comes from `leptos_meta::Html`, whose spread attributes take a reactive `class` closure, so the `<html>` element follows the signal on the client and is rendered with the right class on the server.

Persistence is where a naive version flashes. The toggle writes the choice to `localStorage` under a `theme` key inside an `Effect::new`, which Leptos runs only in the browser, so server rendering never touches `window`. Reading it back during hydration would be too late: the page would paint light and then switch. So the agent adds one small inline `<script>` to `shell`, before the stylesheet, that reads the key and sets the class on `document.documentElement` before first paint, and the signal's initial value on the client reads the same key through `leptos::prelude::window()` and the `web_sys` it re-exports, so no new crate goes into `Cargo.toml`. The toggle also carries `aria-pressed` and a visible label so it is usable without the icon.

The project tests with Playwright: `end2end/tests/example.spec.ts` opens `http://localhost:3000/` and checks the title and heading, and `end2end-cmd` in `Cargo.toml` runs `npx playwright test` across chromium, firefox and webkit. The agent adds `end2end/tests/theme.spec.ts`: click the toggle, expect `html` to have class `dark`, reload, expect it still there with no `light` class in the first `innerHTML` snapshot, then click back to `System` and expect the class gone. It installs the nightly toolchain `rust-toolchain.toml` names, the `wasm32-unknown-unknown` target, `cargo-leptos` and `sass` as the README lists, runs `npm install` and `npx playwright install --with-deps` in `end2end/`, then `cargo leptos end-to-end`, which builds, starts the server and runs the suite, before opening the pull request.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add a dark mode toggle to this Leptos app. Read Cargo.toml, rust-toolchain.toml, src/app.rs, src/main.rs, src/lib.rs, style/main.scss, end2end/playwright.config.ts, end2end/tests/example.spec.ts and README.md first. Use CSS custom properties with a prefers-color-scheme default and html.dark and html.light overrides, keep the theme in a signal provided through context, set the class on the html element through leptos_meta, and persist the choice in localStorage from an effect so server rendering never touches window. Add an inline script in the shell that applies the stored class before first paint so a reload does not flash. Give the toggle a visible label and aria-pressed. Add a Playwright test in end2end/tests that toggles, reloads and checks the class persists. Install the toolchain, cargo-leptos, sass and the Playwright browsers in the sandbox, run cargo leptos end-to-end, and open a pull request that shows the test output.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

What comes back is a pull request that changes `src/app.rs` (the `Theme` type, the context, the `ThemeToggle` component, the `Html` class and the inline script in `shell`), `style/main.scss` (the custom properties and the three colour blocks) and adds `end2end/tests/theme.spec.ts`. `Cargo.toml` is unchanged, and the pull request says so explicitly: no dependency was added. The description shows the `cargo leptos end-to-end` output with the new test's name against each of the three browsers and a short note on where the pre-paint script sits and why.

The run's record keeps the toolchain install, the `cargo leptos build`, the server start and the Playwright run, so a reviewer can see the test passed in a real browser rather than read a claim that it would.

Before merging, a reviewer looks at the colour values the agent chose for the dark palette, decides whether the toggle belongs in a header component the real app will grow, and whether `System` should stay a third state or the toggle should be a plain two-way switch. The agent leaves the counter, the router and the `HydrationScripts` setup as they were.

## Run it on every Linear issue labelled dark-mode

A team that tracks front-end work in Linear makes an automation on the Project with a `linear` trigger on issues given the `dark-mode` label and this prompt. The trigger appends the issue, with its title and description, after the prompt, so a request like "only the settings page for now" reaches the agent as written. Each firing starts one run with its own sandbox and opens its own pull request that links the issue.

A team without Linear starts the run from its own server with `POST /o/{org}/sessions`, the repository in `resources` and a `request_id` that is a UUID v5 of the issue or ticket id, so a retry returns the run already started.

## Why run it on Rush?

Dark mode in a hydrating app is easy to get subtly wrong and hard to notice in a code review: `window` touched during server rendering panics the Axum handler, `localStorage` read after hydration flashes light on every reload, and a class set on `body` in one place and `html` in another disagrees with the stylesheet. The agent runs the real `cargo leptos` build in its own sandbox and the real browsers through Playwright, so a flash or a panic shows up in the record before a reviewer opens the diff.

The build log and the test run stay with the run, and the pull request cites them. Running the same job across several Leptos front-ends costs the same attention as one, because each run has its own machine, its own log and its own pull request.

## Frequently asked questions

### Why an inline script in the shell?

Because the stylesheet is applied before the WebAssembly bundle loads and hydrates. Anything the Rust side does with `localStorage` happens after first paint, so a visitor who chose dark would see a light frame on every reload. A few lines of JavaScript in `shell`, run before the stylesheet, set the class on `<html>` from the stored key first; the Leptos signal then starts from the same key and takes over.

### Why set the class on html rather than body?

The pre-paint script can only reach `document.documentElement` that early, and the CSS overrides are written as `html.dark` and `html.light`. `leptos_meta` offers both `Html` and `Body` with spread attributes, so the choice is about keeping one element as the source of truth, not about what the crate can do.

### Will it add a crate?

No. `leptos::prelude::window()` and the `web_sys` types Leptos re-exports are enough to read and write `localStorage`, and the effect that does so only runs under the `hydrate` feature's client build. `Cargo.toml` keeps the dependency list it has.

### What does System mean?

No class on `<html>`, so the `@media (prefers-color-scheme: dark)` block decides. Choosing `Light` or `Dark` sets the class and wins over the media query; choosing `System` again removes the stored key. The Playwright test checks the class, and uses `page.emulateMedia` to check the system state in both schemes.

## More Leptos jobs

- [Add a Dockerfile to a Leptos Axum App](https://getrush.ai/run/add-dockerfile/leptos/)
- [Add GitHub Actions CI to a Leptos App](https://getrush.ai/run/add-github-actions-ci/leptos/)
- [Add Graceful Shutdown to a Leptos Axum Server](https://getrush.ai/run/add-graceful-shutdown/leptos/)

## The same job on other stacks

- [Add Dark Mode to a Lit Component](https://getrush.ai/run/add-dark-mode/lit/)
- [Add Dark Mode to a Pelican Blog](https://getrush.ai/run/add-dark-mode/pelican/)
- [Add a Dark Mode Toggle to a Phoenix LiveView App](https://getrush.ai/run/add-dark-mode/phoenix-liveview/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
