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.