No-flash theme bootstrap script

interlace-ui/theme-script

FreeUtility

@interlace/ui — the inline `<head>` script that applies the stored theme before first paint. Without it every page load flashes the default theme.

Install it

npx shadcn@latest add https://ds.interlace.tools/r/theme-script.json

Source

registry/interlace-ui/lib/theme-script.tsds.interlace.tools/r/theme-script.json · first 6 KB

1import { DEFAULT_THEME, THEMES } from '@/lib/theme-tokens';
2 
3// @interlace/theme-script v1.0.1 — Interlace design system.
4// Docs, props and live preview: https://ds.interlace.tools/c/theme-script
5// What changed since: https://ds.interlace.tools/c/theme-script#history
6// Generated banner — keep it, the upgrade diff reads this version.
7 
8/**
9 * @interlace/ui — the no-flash theme bootstrap.
10 *
11 * A theme applied after hydration is a WHITE FLASH on every page load: the
12 * document paints `:root` (Interlace · light) first, React mounts, an effect
13 * reads localStorage, and only then does the page repaint into the dark or
14 * re-branded palette the user actually chose. On a fast connection that is
15 * one frame of the wrong colours; on a slow one it is half a second of a
16 * blinding white page. It is the single most visible failure mode of a theme
17 * system, and no amount of correctness in the hook fixes it — by the time
18 * any React code runs, the wrong paint has already happened.
19 *
20 * The only fix is to write the DOM attributes BEFORE first paint, which means
21 * a synchronous, blocking, inline `<script>` in `<head>`. Hence a string
22 * constant rather than a component: it has to be inlined by the host
23 * document, and the host is the only thing that can put it there.
24 *
25 * ─── How consumers use it ─────────────────────────────────────────
26 *
27 * Next.js App Router (`app/layout.tsx`) — server component, no 'use client':
28 *
29 * ```tsx
30 * import { THEME_SCRIPT } from '@interlace/ui/theme-script';
31 *
32 * <html lang="en" suppressHydrationWarning>
33 *   <head>
34 *     <script dangerouslySetInnerHTML={{ __html: THEME_SCRIPT }} />
35 *   </head>
36 * ```
37 *
38 * `suppressHydrationWarning` on `<html>` is required and is the same thing
39 * next-themes asks for: the script deliberately mutates the element React is
40 * about to hydrate, so the server markup and the client DOM differ by
41 * design. It suppresses the warning for that one element's attributes only.
42 *
43 * Vite / plain HTML: paste the string into `<head>` as an inline script, or
44 * emit it at build time. It has no imports and no dependencies.
45 *
46 * ─── What it deliberately does NOT do ─────────────────────────────
47 *
48 * No feature detection beyond what it needs, no polyfills, no error
49 * reporting. It is wrapped in one `try` and fails silently, because a
50// … truncated

More from interlace-ui

All 140 items

Same registry, same kind — the ones you would have found next
Component	Registry	Kind	Access	Installs
cn — class-name merge utilitycn	interlace-ui	Utilities	Free	no deps
Theme token manifesttheme-tokens	interlace-ui	Utilities	Free	no deps
useReducedMotion hookuse-reduced-motion	interlace-ui	Utilities	Free	no deps
useTheme hookuse-theme	interlace-ui	Utilities	Free	no deps