---
title: ClientRouter
description: How the theme survives navigation with Astro's ClientRouter, and the one assumption this relies on.
---

With Astro's [`ClientRouter`](https://docs.astro.build/en/guides/view-transitions/) a navigation swaps the DOM instead of loading a new document. The incoming page comes from the server without a theme, so something has to put it back. Astro Eclipse handles it with no setup beyond adding `ClientRouter` to your layout.

## How the theme survives

The inline [head script](/reference/head-script) listens for `astro:before-swap`. That event fires before the swap and exposes the incoming document as `event.newDocument`. The script applies the current theme to `newDocument.documentElement` (the attribute, or the classes), so the swapped-in page already has it when it is attached. The page never paints with the wrong theme.

The script and the client API are not re-created on navigation. Listeners added by `onThemeChange` stay valid as long as the document does.

## Theme changes during a navigation

If `setTheme` is called while Astro is navigating, the theme is applied at once without a View Transition. Astro is already running its own transition, and starting a second one would cancel it and leave the navigation half done.

There are two checks. Astro fires `astro:before-preparation` when a navigation starts and `astro:after-preparation` once the next page is fetched, so a theme change is instant between the two (and for at most 15 seconds, in case a navigation never reports back). After the fetch, Astro starts its own view transition and sets `data-astro-transition` on `<html>` until the page has swapped, which is the second check.

:::warning[The one risk]
`data-astro-transition` is an implementation detail of Astro, not a documented API. It was found by reading Astro's source. The end-to-end tests check the fetch phase (no view transition of ours starts) and that toggling during a slowed navigation leaves the page on a consistent theme, on Astro 7 only. If a future Astro release renames or removes it, a theme change during a navigation would start a second View Transition. The page would still end on the right theme, but Astro's own transition could be cut short. Check this after upgrading Astro.
:::

## Buttons that get replaced

A button inside the swapped content is a new element after each navigation, and a script bound to the old one is gone. Bind once on `document` and match the button there:

```astro src/layouts/Layout.astro
---
import { ClientRouter } from 'astro:transitions'
---

<html lang="en">
  <head>
    <ClientRouter />
  </head>
  <body>
    <slot />
    <script>
      import { toggleTheme } from 'astro-eclipse/client'

      document.addEventListener('click', (event) => {
        if (event.target instanceof Element && event.target.closest('[data-theme-toggle]')) {
          toggleTheme({ origin: event })
        }
      })
    </script>
  </body>
</html>
```

```html
<button type="button" data-theme-toggle aria-label="Toggle dark mode">Theme</button>
```

Bundled `<script>` tags in Astro run once, so the listener is not added twice.

## Persisted islands

An island kept across navigation with `transition:persist` keeps its state, and so does its `onThemeChange` subscription. The [hooks](/guides/framework-islands) clean up only when the component is destroyed.

### Keep the toggle with `transition:persist`

If the toggle lives in a layout that every page shares, you can keep the same DOM node across navigations instead of letting it be replaced:

```astro src/layouts/Layout.astro
---
import { ClientRouter } from 'astro:transitions'
import { ThemeToggle } from 'astro-eclipse/components'
---

<html lang="en">
  <head>
    <ClientRouter />
  </head>
  <body>
    <header>
      <ThemeToggle transition:persist />
    </header>
    <slot />
  </body>
</html>
```

The label stays correct because `ThemeToggle` refreshes it on theme changes and on `astro:page-load`, and its single click listener lives on `document`, so nothing needs rebinding. A persisted toggle also means the focus ring and any open state in a custom toggle survive the navigation. Use the same attribute on a custom toggle if you prefer; its label must then be updated from `onThemeChange`.

This was run in a scratch project with Astro 7.4.8 and astro-eclipse 1.2.0, in Chromium with reduced motion. The same `<button>` node was still there on the second page (a marker set on it survived), its name read `Theme: dark. Switch to light` straight after the navigation, and clicking it there switched the theme. Other browsers and motion were not run.

Without `ClientRouter`, see [multi-page sites](/guides/multi-page).

Related: [accessibility](/guides/accessibility), [transitions](/guides/transitions#when-it-switches-instantly).
