Headless, framework-agnostic theme state: the choice in a cookie, the resolved theme on <html>. No flash, SSR-ready.
- Cookie-first. The choice lives in a cookie, so the server can render it and every tab shares it.
- Set before the first paint. A tiny inline script sets
<html>from the visitor's cookie, even on static or cached pages. - One store, any framework.
get,setandsubscribe, with a React adapter of a few lines on top. - More than light and dark. Add independent themes, like contrast or density, side by side.
npm i @ttydiy/react-theme # React
npm i @ttydiy/theme # any other framework, or none// theme.ts
import { createTheme } from '@ttydiy/react-theme' // or '@ttydiy/theme'
export const colorTheme = createTheme()Every option is optional, so pass only what you want to change. The main ones, at their defaults:
export const colorTheme = createTheme({
themes: ['light', 'dark'], // plus 'system', which follows the OS
attribute: 'data-theme', // or 'class', for class="dark"
cookie: 'theme',
})All options are in the API.
It renders the theme on <html> before the page paints, and again on every change. Put it first in <head> on every page.
Next.js
// app/layout.tsx
import { themeScript } from '@ttydiy/react-theme'
import { colorTheme } from './theme'
export default function RootLayout({ children }: LayoutProps<'/'>) {
return (
<html lang="en" suppressHydrationWarning>
<head>
<script>{themeScript(colorTheme)}</script>
</head>
<body>{children}</body>
</html>
)
}Example, with shadcn/ui.
TanStack Start
// src/routes/__root.tsx
import { ScriptOnce } from '@tanstack/react-router'
import { themeScript } from '@ttydiy/react-theme'
import { colorTheme } from '../theme'
function RootDocument({ children }: { children: React.ReactNode }) {
return (
<html lang="en" suppressHydrationWarning>
<head>
<ScriptOnce>{themeScript(colorTheme)}</ScriptOnce>
<HeadContent />
</head>
<body>
{children}
<Scripts />
</body>
</html>
)
}To show the saved theme in server-rendered components too, see Server rendering.
Vite
// vite.config.ts
import { themeScript } from '@ttydiy/react-theme'
import { colorTheme } from './src/theme.ts'
export default defineConfig({
plugins: [
react(),
{
name: 'theme-script',
transformIndexHtml: () => [
{ tag: 'script', children: themeScript(colorTheme), injectTo: 'head-prepend' },
],
},
],
})Any other framework
themeScript returns the script as a string. Add it to your HTML however your framework renders <head>:
import { themeScript } from '@ttydiy/theme'
const head = `<script>${themeScript(colorTheme)}</script>`:root { background: #fff; color: #0a0a0a; }
[data-theme='dark'] { background: #0a0a0a; color: #fafafa; }Using Tailwind, shadcn/ui or another CSS library? See Styling.
'use client'
import { useTheme } from '@ttydiy/react-theme'
import { colorTheme } from './theme'
export function ThemeToggle() {
const [theme, setTheme] = useTheme(colorTheme)
return <button onClick={() => setTheme(theme === 'dark' ? 'light' : 'dark')}>{theme}</button>
}Without React:
colorTheme.get() // 'light' | 'dark' | 'system'
colorTheme.set('dark')
colorTheme.subscribe((theme) => {})One cookie holds the user's choice, and everything reads from it:
setTheme('dark') ──► cookie ──► the server, on every request
│
├──► other tabs
▼
the script, on the first paint and every change ──► <html data-theme="dark" style="color-scheme: dark"> ──► your CSS
- Cookie as the source of truth. Most theme libraries use
localStorage, which only the browser can read. A cookie also reaches the server, so the server, the script and every tab agree. - One renderer. A small blocking script in
<head>renders the choice before the first paint, so there's no flash of the wrong theme. It also renders every later change: the store saves the choice and asks the script to show it. <html>as output only. The script writes the theme andcolor-schemethere, and nothing reads them back.'system'resolved in the browser. It followsprefers-color-scheme, and updates live when the OS changes.- A framework-agnostic store.
get,setandsubscribe, the contract React'suseSyncExternalStoreexpects, so each framework adapter is a few lines. - Hydration without mismatches. The server passes the request's choice to the client, so both render the same value.
- Tabs in sync. Through the
cookieStorechange event. A page restored from the back/forward cache rechecks the cookie.
The library sets the theme on <html>, and any CSS can style it. Pick the attribute your CSS expects:
| Using | Option | Style |
|---|---|---|
| Plain CSS | Default | [data-theme='dark'] { … } |
| Tailwind | Default | Add the dark: variant below |
| shadcn/ui | attribute: 'class' |
Nothing to add: its globals.css styles .dark |
| daisyUI | Default | Nothing to add: it reads data-theme. List your daisyUI themes in themes. |
| Radix Themes | attribute: 'class' |
Nothing to add: it reads .light and .dark |
Tailwind's dark: variant, for data-theme:
@custom-variant dark (&:where([data-theme=dark], [data-theme=dark] *));The script also sets color-scheme, so native controls, scrollbars and light-dark() follow the theme. Tailwind compiles light-dark() to a fallback that reads color-scheme from your CSS, so with Tailwind, also add:
[data-theme='light'] { color-scheme: light; }
[data-theme='dark'] { color-scheme: dark; }The script gets the colors right in every setup. Server rendering only matters for components that show the theme itself, like a toggle that says "Dark".
On the server, useTheme doesn't know the cookie, so it returns 'system', then updates right after the page loads. To render the saved choice from the start, pass it from the server with ThemeHydrationBoundary. In TanStack Start:
// src/routes/__root.tsx
import { createServerFn } from '@tanstack/react-start'
import { getRequestHeader } from '@tanstack/react-start/server'
import { ThemeHydrationBoundary } from '@ttydiy/react-theme'
const getThemeState = createServerFn().handler(() =>
colorTheme.dehydrate(getRequestHeader('cookie')),
)
export const Route = createRootRoute({
loader: () => getThemeState(),
shellComponent: RootDocument,
})
// in RootDocument's <body>:
<ThemeHydrationBoundary state={Route.useLoaderData()}>{children}</ThemeHydrationBoundary>| Setup | Script | suppressHydrationWarning |
ThemeHydrationBoundary |
|---|---|---|---|
Server-rendered (Next.js, Start ssr: true) |
Yes | Yes | Optional |
Client-rendered in a server shell (Start ssr: false or 'data-only') |
Yes | Yes | No |
| Single-page app (Vite) | Yes | No | No |
Only use the boundary on pages rendered per request. On a page cached for everyone, it would show one visitor's choice to others until the page loads.
Need more than light and dark, like a contrast or density setting? Create one theme per setting, each with its own attribute and cookie:
export const contrast = createTheme({
themes: ['more', 'less'],
attribute: 'data-contrast',
cookie: 'contrast',
})Add a script for each, and pass both to the boundary:
<ThemeHydrationBoundary state={{ ...colorTheme.dehydrate(cookies), ...contrast.dehydrate(cookies) }}>- Keep
lightanddarkin one theme. Only that one setscolor-scheme. - For other settings,
'system'removes the attribute or class, so your CSS default applies. - Give each theme its own cookie and attribute.
attribute: 'class'can be shared, as long as the theme names differ.
| Option | Default | |
|---|---|---|
themes |
['light', 'dark'] |
Themes besides 'system' |
attribute |
'data-theme' |
Attribute on <html>, or 'class' |
cookie |
'theme' |
Cookie name |
cookieAttributes |
'path=/;max-age=31536000;samesite=lax' |
Replaces the default. To share across subdomains: 'path=/;domain=.example.com;max-age=31536000;samesite=lax' |
| Returns | |
|---|---|
get() |
The choice: a theme or 'system' |
set(theme) |
Takes a theme, 'system' or an updater |
subscribe(listener) |
Calls listener on every change, including from other tabs. Returns unsubscribe. |
parse(cookieHeader) |
Reads the choice from a Cookie header, on the server |
dehydrate(cookieHeader) |
The choice as state for ThemeHydrationBoundary |
The script, as a string. Every page needs it: it renders the first paint and every change after. Without it, set still saves the choice, but <html> doesn't change. Its output only changes with the options, so a strict Content Security Policy can allow it by hash.
Returns [theme, setTheme].
Gives useTheme the server's choice while the page hydrates.
Browsers. The script and store need the DOM and cookies, so React Native isn't supported. Electron and Tauri are untested. parse and dehydrate work in any JavaScript runtime.
MIT