@themvora/astro

This entry point is framework-neutral: it ships the Astro integration (themvora), the zero-flash server helpers (createBlockingScript, buildThemeCssMap, darkModeCSSTemplate, systemModeCSSTemplate, computeFingerprint, getInitialThemeState), the Astro-specific ThemePersistence, the browser-side getThemeController() / createThemeController() API, the shared-runtime accessors, and the framework-neutral ThemvoraScrollbar / ThemvoraInspector re-exports from @themvora/web. None of it imports React.

The React island (ThemeProviderClient), the React hooks, and the React ThemeScope live behind the opt-in @themvora/astro/client subpath, which is the only entry that depends on React.

Generated from packages/astro/src by apps/docs/scripts/generate-api-reference.mjs. Do not edit by hand — run pnpm --filter @themvora/docs api:generate.

Functions

buildThemeCssMap<T extends ThemeDefinition<string>>(themes, options?): Record<string, Record<string, string>>

Build a lookup map of theme keys to flat CSS variables.

Each theme is registered twice:

• under its own name (e.g. "sunrise-light")
• under a family:mode key (e.g. "sunrise:light") so that a persisted family + effective mode can be resolved without knowing theme names.

See also: createThemeBootstrapScript

Returns Record<string, Record<string, string>>

computeFingerprint(themes, defaultTheme?): string

Fingerprints a theme registry so a persisted selection from an older build — different themes, or a different defaultTheme — is ignored rather than applied against themes it was never valid for.

See also: ThemeBootstrapCookieSource, buildBootstrapPlan

Returns string — A stable fingerprint string, or "" when themes is empty.

The result is written to the theme-fingerprint cookie and compared on the next request, so it is part of the stable cookie contract documented in VERSIONING.md — changing the format invalidates every visitor's persisted selection on their next visit.

It lives here, in core, because four SSR integrations (Next, Nuxt, Astro, Remix) previously each carried a byte-identical private copy. Any edit to one of them would have silently broken cross-framework persistence with nothing to catch it.

createAstroThemePersistence(themes?, defaultTheme?): ThemeSelectionPersistenceAdapter | null

Creates the client-side persistence adapter for Astro. Mirrors the theme selection to localStorage (cross-tab sync, offline) AND to the theme cookies (theme-family / theme-mode / theme-fingerprint) so the server resolves the exact same state on the next request.

Reads from both: localStorage first, then the cookies. Reading the cookies as well is what keeps the client runtime in agreement with the pre-paint bootstrap script, which only ever sees cookies — a read path that ignored them made the runtime overwrite an already-correct first paint.

See also: ThemeProviderClient

Returns ThemeSelectionPersistenceAdapter | null — A persistence adapter, or null when running outside the browser.

Returns null during SSR (no window). The cookie contract matches the other SSR integrations (@themvora/next, @themvora/nuxt, @themvora/remix).

Blocked storage degrades, it does not throw. window.localStorage can throw on access and setItem throws when the quota is full; both are treated as "this browser cannot remember the selection". The cookie mirror is written either way, so the server still resolves the same theme on the next request.

createBlockingScript(fingerprint, themeCssMap, options): string

Builds the blocking, inline bootstrap script that applies the persisted theme before first paint (zero-flash).

The script reads the theme cookies, rejects them when the config fingerprint is stale, resolves the effective mode ("system" against prefers-color-scheme), and writes the CSS variables plus the full DOM contract the client runtime applies — data-theme, data-theme-family, data-theme-mode, the dark class and color-scheme — onto document.documentElement. Hydration therefore confirms the server-rendered theme instead of correcting it.

It is deliberately tiny and synchronous: no runtime, no listeners, no storage access beyond cookies, and no framework dependency.

See also: buildThemeCssMap, buildThemeBootstrapPayload, darkModeCSSTemplate

Returns string — The inline script string to emit in the document <head>.

Pass options so a visitor with no valid cookies is resolved against the same fallback the runtime uses. Without it the script still corrects the mode marker and uses the first matching family:mode entry it finds, but it cannot guarantee it agrees with the client runtime.

createThemeController<T extends ThemeDefinition<string>>(options): ThemeController<T>

Creates a controller over a new runtime and installs it as the app-wide runtime.

See also: getThemeController, ThemeController

Returns ThemeController<T> — A new controller owning a new runtime.

Prefer getThemeController in application code: this function replaces any runtime already installed, so two calls give two runtimes racing to write <html>.

import { createThemeController } from "@themvora/astro";

const theme = createThemeController({ themes: myTestThemes });
theme.setMode("dark");

darkModeCSSTemplate(variables): string

Generate a @media (prefers-color-scheme: dark) CSS block carrying the given variables.

See also: systemModeCSSTemplate

Returns string — A @media (prefers-color-scheme: dark) block targeting :root, escaped so it cannot terminate a <style> element (</ becomes </, which CSS parses identically).

This is a pre-script fallback only, and it cannot beat an inline style on the same element: inline declarations outrank every stylesheet rule regardless of specificity. So it is only safe when nothing inlines the light variables — do not pair it with a server render that writes them onto <html>, or an OS-dark visitor keeps the light ones and this block is inert. When the resolved mode is "system", use systemModeCSSTemplate instead: it emits both schemes and expects no inline variables.

getGlobalRuntime<T extends ThemeDefinition<string>>(): ThemeRuntime<T> | null

Returns the app-wide global runtime, or null when none has been installed yet (e.g. before ThemeProviderClient mounts).

See also: setGlobalRuntime

Returns ThemeRuntime<T> | null — The installed runtime, or null.

getInitialThemeState<T extends ThemeDefinition<string>>(request, options): Promise<InitialThemeResolution<T>>

Resolves the initial theme state server-side from the incoming request's theme cookies, so the server-rendered HTML is already themed and a client island can hydrate against the exact same state (zero-flash).

Framework-neutral: only reads the standard theme-mode / theme-family cookies, the optional Sec-CH-Prefers-Color-Scheme client hint, and the theme registry, so it works from any Astro server context (Astro.request) without pulling in a client framework runtime.

See also: - provider.astro`

• `ThemeProviderClient``

Returns Promise<InitialThemeResolution<T>> — The resolved initial theme state.

Pair this with provider.astro (which paints the themed <html> on the server) and pass the result to the opt-in React island (@themvora/astro/client) as its initial prop so hydration matches.

---
import { getInitialThemeState } from "@themvora/astro";
import { getBuiltInThemes } from "@themvora/core";

const initial = await getInitialThemeState(Astro.request, {
  themes: getBuiltInThemes(),
  defaultTheme: "mint-light",
  mode: "system",
  systemPreference: true,
});
---

getThemeController<T extends ThemeDefinition<string>>(options): ThemeController<T>

The app-wide ThemeController, created on first call.

See also: ThemeController, createThemeController, getGlobalRuntime

Returns ThemeController<T> — The shared controller.

One runtime per document. The provider, <ThemeToggle />, a hand-written <script> and a React island all end up here, and the first caller wins: every later call returns the same controller rather than building a second runtime that would fight the first over <html>. That is what lets a page go from <Provider> to <ThemeToggle /> with no per-page initialMode / initialFamily and no React island.

If a runtime is already installed — a React island created one — this adopts it instead of replacing it, so the two surfaces share one runtime and one state.

Browser-only. It reads the transported configuration, the persisted selection and prefers-color-scheme, none of which exist on a server — call it from a <script>, never from Astro frontmatter.

<button id="theme-toggle">Toggle theme</button>

<script>
  import { getThemeController } from "@themvora/astro";

  const theme = getThemeController();

  document
    .querySelector("#theme-toggle")
    ?.addEventListener("click", () => theme.toggleTheme());
</script>

injectPrePaintScrollbarCSS(): void

Injects the pre-paint scrollbar-hiding CSS and class into the document.

Framework-free (vanilla JS). Adds a <style> carrying the pre-paint scrollbar CSS and the tv-scrollbar class to the document root so the native scrollbar is hidden before first paint. Idempotent and a no-op on the server.

This is a manual bootstrap helper for a page that wants the native bar hidden before its own script runs. It is not how ThemvoraScrollbar hides the bar — that happens through createOverlayScrollbar, which claims the hiding and gives it back on destroy(). Calling this directly therefore hides the bar without registering a claim, so pair it with restoreNativeScrollbar() if you later want the native bar back.

See also: ThemvoraScrollbar

Returns void

installThemeBindings(): void

Installs the delegated DOM bindings for the Themvora contracts.

See also: THEME_SELECTION_ATTRIBUTE, THEME_TOGGLE_ATTRIBUTE

Returns void

Two contracts, one listener each, registered once per document:

The change listener is the input half of [data-tv-select]; the output half — writing the live selection back into the element — lives in syncSelectionControls, and [data-tv-pressed] (a segmented control's aria-pressed) is mirrored by syncPressedControls on the same change. A page that renders <ThemeToggle /> and a segmented control therefore needs no script of its own, and the two controls cannot disagree.

Delegated, not per-element. This is the fix for the interaction bug, not a style preference. Astro bundles a component's <script> once per page, so a component that rendered the select cannot know how many instances the page has — getElementById binds one of them. And Astro's module scripts never re-execute across <ClientRouter /> navigations, so a page you navigate back to keeps the listeners its first visit registered and no others. A document-level listener has neither problem: it is registered once and matches whatever the DOM contains at the moment the event fires.

Lazy. Nothing here creates a runtime. The controller is resolved on the first interaction, so a page that renders a control but is never used ships the script and pays nothing else — the runtime, its persistence adapter and its cross-tab channel are still created on demand.

Safe to call more than once, and safe to call on the server (a no-op).

<select data-tv-select="family">
  <option value="mint">mint</option>
  <option value="cocoa">cocoa</option>
</select>

<script>
  import { installThemeBindings } from "@themvora/astro/runtime";
  installThemeBindings();
</script>

requireGlobalRuntime<T extends ThemeDefinition<string>>(): ThemeRuntime<T>

Returns the app-wide global runtime, throwing when none has been installed.

See also: getGlobalRuntime, setGlobalRuntime

Returns ThemeRuntime<T> — The installed runtime.

setGlobalRuntime<T extends ThemeDefinition<string>>(runtime): void

Installs the given runtime as the app-wide global runtime and, in the browser, publishes it where the rest of Themvora looks for it.

See also: getGlobalRuntime

Returns void

Three publications, all of them the same runtime:

1. the module-level globalRuntime — what this package's hooks read;
2. window.__themvoraRuntime — the documented escape hatch;
3. document.documentElement.__themvoraRuntime plus a theme-ready event — which is how @themvora/web's custom elements (<themvora-scrollbar>, <themvora-inspector>, <themvora-toggle>, …) find a runtime. They resolve it by walking DOM ancestors for that property, and they only fall back to waiting for theme-ready, which until now was dispatched solely by <themvora-provider>. Without these two lines an Astro app that installs its runtime from a React island had no way to use the framework-neutral elements at all — the runtime existed, but nothing in the element tree could see it.

systemModeCSSTemplate(light, dark): string

Generate the stylesheet that resolves a "system" selection with CSS alone — no script and no inline style.

See also: darkModeCSSTemplate

Returns string — Two media blocks, one per scheme, both targeting :root, escaped for <style>-element content exactly as darkModeCSSTemplate is.

Use this instead of inlining the resolved variables whenever the mode is "system". The two cannot be combined: an inline style on <html> outranks any stylesheet rule, so a page that inlines the light variables and also emits a dark media block paints light whatever the OS prefers. Measured on a production build with page scripts blocked and the OS set to dark, that combination painted rgb(248, 250, 252) (light); emitting both media blocks and no inline variables painted rgb(2, 6, 23).

prefers-color-scheme: light also matches when the visitor has expressed no preference — light is the specified default — so the light block doubles as the no-preference branch.

themvora(options): AstroIntegration

Themvora Astro integration. Registers the pre-paint theme bootstrap with Astro so every page is themed before first paint (zero-flash), without requiring a client-side framework runtime.

See also: ThemvoraIntegrationOptions

Returns AstroIntegration — An Astro integration to register in astro.config.ts.

Config discovery. The integration finds the application's theme.config.ts in Astro's root, trying theme.config.ts, .tsx, .mts, .mjs, .js and .cjs in that order, and requires a default export — the object defineThemvoraConfig returns. Passing config skips discovery and accepts either the object or a path to it.

Two consumers, one declaration. The discovered configuration is projected twice: buildBootstrap derives the blocking script from it, and the same projection is injected as window.__THEMVORA_CONFIG__ from <head>. The island reads that global instead of taking theme props, so the markup the server renders and the markup the browser hydrates come from the same registry — a mismatch there is visible as the panel repainting as the real families replace the presets. getInitialThemeState publishes the same global on the server, because no integration runs there.

When the app has no discoverable config, the built-in neutral themes are used and nothing fails.

The integration owns the framework/build boundary only. Server-rendering the themed <html> element is handled by @themvora/astro/provider.astro, and interactive controls are opt-in islands — React users import the island from @themvora/astro/client, which is the only entry that depends on React.

The bootstrap is injected at the head-inline stage, and that choice is load-bearing rather than incidental. before-hydration looks equivalent — both run before the island hydrates — but it ships the script as a module (resolved and bundled by Vite), so it executes after the browser has already painted. Measured on a prerendered page, where the server cannot know the visitor's selection and always emits the default theme:

So before-hydration does not merely weaken the guarantee — it produces a visible flash of the wrong theme, up to ~540 ms of it. Paint ordering requires the inline head script; pre-hydration is not sufficient.

For a "system" selection the script is not the first line of defence — CSS is. The server cannot know the visitor's preference, so it must not commit to one: an inline style on <html> outranks every stylesheet rule, which means inlining a guess would silently defeat the prefers-color-scheme block meant to correct it. Measured on the built example with page scripts blocked and the OS set to dark, the inline-variables-plus-dark-block combination painted the light canvas (rgb(248, 250, 252)); emitting both schemes as media blocks and no inline variables paints rgb(2, 6, 23). See systemModeCSSTemplate.

Client-side navigation (<ClientRouter />) is handled separately by createNavigationScript — the injected bootstrap is byte-identical on every page, so Astro de-duplicates it and it does not re-run, and the live theme state would otherwise be replaced by the destination page's build-time attributes.

// Register the integration. No theme data.
import { defineConfig } from "astro/config";
import themvora from "@themvora/astro";

export default defineConfig({
  integrations: [themvora()],
});

Classes

class ThemvoraInspector

Extends ThemvoraRuntimeConsumer Custom element <themvora-inspector> that inspects the active theme.

Framework-free (vanilla JS). Renders a floating toggle that opens a panel showing the active theme's identity, selection, tokens, and resolved CSS variables, updating live as the theme changes. Observes the bottom, right, size, and z-index attributes.

See also: defineCustomElements, ThemvoraProvider

Attributes. All four are positional and optional:

• bottom — distance from the bottom of the viewport, in px (default 104).
• right — distance from the right edge, in px (default 32).
• size — toggle button size, in px (default 40).
• z-index — stacking order of the toggle and panel (default 9999).

Non-numeric values are ignored in favour of the default.

Properties. None of its own beyond the standard HTMLElement surface.

Events. Dispatches nothing of its own.

Slots. None — the panel is built from the runtime's data.

Requires an ancestor <themvora-provider>. If the provider is not yet initialized, it waits for the theme-ready event. define() is SSR-safe and no-ops when customElements is unavailable.

<themvora-inspector bottom="24" right="24"></themvora-inspector>

class ThemvoraScrollbar

Extends ThemvoraRuntimeConsumer Phase 2 — ThemvoraScrollbar (Web Component): overlay only.

Creates the custom scrollbar overlay.

Lifecycle: connectedCallback → resolve the runtime ↓ onRuntime → hide native bar (Phase 1) → create overlay → attach ↓ (Phase 2) later → add tv-scrollbar-ready ↓ (Phase 3) onDetach / destroy → remove overlay → restore native bar

Phase 1 happens synchronously inside the overlay's construction. For static HTML served via the Vite plugin (scrollbar: true), the pre-paint script in

The teardown is a real teardown. The hiding is claimed, not switched on, so removing the element gives the native scrollbar back instead of leaving the page with no scrollbar at all — and an attribute change swaps the overlay without ever passing through the "hidden, but nothing drawn" state.

See also: ThemvoraProvider

Attributes. Every option is an attribute; changing one rebuilds the overlay. Booleans are presence-based: present (any value except false or 0) enables, absent or false disables. Numbers are unitless pixels.

• Behaviour — auto-hide, auto-hide-delay, hover-expand, draggable, click-to-jump, smooth, overscroll, touch.
• Arrows — arrows, arrow-icon, arrow-up-icon, arrow-down-icon, arrow-left-icon, arrow-right-icon (SVG markup or URL).
• Geometry — thickness, hover-thickness, radius, min-thumb-size, icon-size, offset (uniform inset), offset-top, offset-right, offset-bottom, offset-left (per-side insets win over offset).
• Motion and paint — track-opacity, thumb-opacity, duration, animation-duration, thumb-color, track-color, active-thumb-color, thumb-hover-color. Colors default to the active theme's tokens.
• Placement — z-index, dir (ltr / rtl / auto), axes (comma-separated vertical / horizontal), include / exclude (comma-separated CSS selectors for the containers to track).

Properties. None of its own beyond the standard HTMLElement surface.

Events. Dispatches nothing of its own; it adds tv-scrollbar-ready to the element once the overlay is measured and attached.

Slots. None — the element renders nothing into the document flow; the overlay it creates lives outside it.

Interfaces

ThemeController<T extends ThemeDefinition>

A framework-neutral controller over the app-wide Themvora runtime.

See also: getThemeController, createThemeController

This is not a React hook, and not a hook of any kind: it is a plain object with getters and setters, valid in any browser context — an Astro <script>, a custom element, an event handler, a devtools console. Nothing here re-renders; ThemeController.subscribe is how a caller observes change.

It exists so Astro does not have to borrow React's shape. A .astro file has no reactive component runtime, so useTheme() — a React hook, valid only inside a React island — is the wrong abstraction there. The Astro-idiomatic spelling is:

const theme = getThemeController();
theme.toggleTheme();

The React hook keeps its own shape, for React islands:

const { theme, mode, toggleTheme } = useTheme();

ThemeControllerState<T extends ThemeDefinition>

The reactive state a ThemeController publishes to its subscribers.

See also: ThemeController.subscribe

ThemvoraIntegrationOptions

Options for themvora. Configures the theme registry the injected bootstrap resolves against and the fallback selection used when no persisted cookie is present.

See also: themvora

Type Aliases

ThemeControllerOptions<T extends ThemeDefinition>

Options for createThemeController / getThemeController.

See also: getThemeController

Partial<Omit<ThemeRuntimeOptions<T>, "persistence" | "readPersistenceOnInit">> & { readouts?: boolean }

Every field is optional, and every field is an override. The application configuration is already in the browser — themvora() transports theme.config.ts as window.__THEMVORA_CONFIG__ from <head> — so the runtime is built from that. Passing themes / defaultTheme / initialMode / initialFamily here is for a test, a storybook, or an island that deliberately wants a different registry.

Variables

THEME_PRESSED_ATTRIBUTE

Marks an element as one option of a segmented control: data-tv-pressed="mode" or data-tv-pressed="family".

See also: THEME_PRESSED_VALUE_ATTRIBUTE, THEME_READOUT_ATTRIBUTE

"data-tv-pressed"

THEME_PRESSED_VALUE_ATTRIBUTE

The option a THEME_PRESSED_ATTRIBUTE element represents, compared against the live mode selection ("light" / "dark" / "system") or the live family selection.

"data-tv-value"

THEME_READOUT_ATTRIBUTE

Opts an element into the bootstrap readout contract: its text is owned by Themvora.

See also: THEME_TOGGLE_ATTRIBUTE

"data-tv-readout"

THEME_SELECTION_ATTRIBUTE

Opts a <select> into the selection-control contract: data-tv-select="family" or data-tv-select="mode".

See also: THEME_TOGGLE_ATTRIBUTE, THEME_READOUT_ATTRIBUTE

"data-tv-select"

THEME_TOGGLE_ATTRIBUTE

Marks an element as a Themvora theme toggle.

See also: THEME_READOUT_ATTRIBUTE

"data-tv-toggle"

Related docs

• Tokens — Semantic token groups are the contract between a theme and the DOM: they flatten to CSS variables, never to hardcoded colors.
• Runtime — One runtime per app owns the store, selection, registry, history, lifecycle and adapters; every framework binding is a thin view over it.
• Persistence — Persist the selection across reloads and requests, with fingerprint validation, storage adapters and theme migrations.
• Zero-flash bootstrap — Paint the correct theme on the first frame: a blocking script plus server-resolved initial state, with a Vite plugin for SPA builds.
• Custom scrollbar — Themed overlay scrollbars that match the active theme and pre-paint before hydration.
• DevTools — Inspect and drive the live runtime from a panel: adapters, history, snapshots and performance entries.
• Astro — the framework integration