Skip to content
Astro Eclipse
Esc
↑↓navigate↵open⌘Jpreview
On this page

ClientRouter

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

With Astro’s ClientRouter 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 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.

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:

---
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>
<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 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:

---
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.

Related: accessibility, transitions.

Was this page helpful?