ThemeInitScript

Usage

Render exactly once per document, as the first child of <head> in a root layout — before any stylesheet that depends on data-theme. The script is blocking by design: no async, no defer, because it must run during HTML parsing, before first paint.

import { ThemeInitScript } from '@epasslive/design-system'

// app/layout.tsx (storefront) — key must equal the theme writer's key
export default function RootLayout({ children }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <head>
        <ThemeInitScript storageKey="epasslive-theme" fallback="dark" />
      </head>
      <body>{children}</body>
    </html>
  )
}

Read order and fallback chain

The script resolves the theme through a fixed chain: storageKey first, then each extraKeys entry in order (first key holding "light" or "dark" wins — this preserves the docs two-key contract); if no key holds a valid value, prefers-color-scheme decides; and if storage AND matchMedia both throw (blocked storage), the fallback prop is applied. The whole body is wrapped in a try/catch and feature-checks window / localStorage / matchMedia, so it never throws on load.

SSR and hydration safety

ThemeInitScript is a pure Server Component: no hooks, no "use client". The script body is derived only from props and every dynamic fragment is escaped through JSON.stringify — no user input is ever interpolated — so the same props always emit the same HTML on server and client (no hydration mismatch). Pair it with suppressHydrationWarning on the <html> element, because the script mutates data-theme before React hydrates.

Props