Theme

Mantle has two themes, light and dark. The stored preference is one of three values: "system" (the default, which follows the OS prefers-color-scheme setting), "light", or "dark". The theme system has two parts:

• ThemeProvider holds the preference, saves it in a cookie, and keeps it in sync across tabs. On an ngrok.com or ngrok.ai host, the cookie covers every subdomain of that site.
• PreventWrongThemeFlashScript puts the right theme class on <html> before first paint, so the page never flashes the wrong theme.

mantle.css holds both themes. The theme class on <html> selects one.

Setup

Wrap your app in ThemeProvider as high in the component tree as you can. Then add PreventWrongThemeFlashScript to <head>, as early as you can.

For SSR apps, send font preloads as HTTP Link response headers with preloadFontLink. The browser then starts each font fetch before it parses any HTML.

1// entry.server.tsx: send font preloads as HTTP Link headers2import { assetsCdnOrigin, preloadFontLink } from "@ngrok/mantle/theme";3 4responseHeaders.set(5	"Link",6	[⋯7		`<${assetsCdnOrigin}>; rel=preconnect; crossorigin`,8		preloadFontLink("roobert"),9		preloadFontLink("jetbrains-mono"),10		preloadFontLink("family-regular"),11	].join(", "),12);

Pass the theme cookie from the request to ThemeProvider and useInitialHtmlThemeProps as ssrCookie. The server then renders the stored theme, and the client hydrates without a mismatch.

1// root.tsx loader: extract the theme cookie so the server renders the stored theme2import { extractThemeCookie } from "@ngrok/mantle/theme";3 4export async function loader({ request }: Route.LoaderArgs) {⋯5	return {⋯6		ssrCookie: extractThemeCookie(request.headers.get("Cookie")),7		// ...other loader data8	};9}

1// root.tsx: place PreventWrongThemeFlashScript in <head>2import {3	PreventWrongThemeFlashScript,4	ThemeProvider,5	useInitialHtmlThemeProps,6} from "@ngrok/mantle/theme";7 8export function Layout({ children }: PropsWithChildren) {⋯9	const loaderData = useRouteLoaderData<typeof loader>("root");10	const initialHtmlThemeProps = useInitialHtmlThemeProps({⋯11		className: "h-full",12		ssrCookie: loaderData?.ssrCookie,13	});14 15	return (16		<html {...initialHtmlThemeProps} lang="en-US" dir="ltr" suppressHydrationWarning>⋯17			<head>⋯18				{/* 👇 add as early as possible in <head> to prevent FOUC */}19				<PreventWrongThemeFlashScript nonce={nonce} />20				<meta charSet="utf-8" />21				<meta name="viewport" content="width=device-width, initial-scale=1" />22				<Meta />23				<Links />24			</head>25			<body>⋯26				<ThemeProvider ssrCookie={loaderData?.ssrCookie}>{children}</ThemeProvider>27			</body>28		</html>29	);30}

Non-SSR / no header control

If you can't set HTTP response headers (a plain Vite SPA, for example), use PreloadFont elements instead of preloadFontLink, and leave out ssrCookie.

1import { PreloadFont, PreventWrongThemeFlashScript } from "@ngrok/mantle/theme";2 3<head>⋯4	<PreventWrongThemeFlashScript nonce={nonce} />5	<PreloadFont name="roobert" />6	<PreloadFont name="jetbrains-mono" />7	<PreloadFont name="family-regular" />8</head>;

Non-React head

If your server can't render React components (a legacy Go service, for example), inline the script into your HTML <head>. Generate the script string with preventWrongThemeFlashScriptContent from @ngrok/mantle/theme: run it in a Node.js build step and embed the output in your template.

The script must run before <body>, because it writes the theme class onto <html> before first paint. To lock the page to one theme, pass it: preventWrongThemeFlashScriptContent("light"). See Locking a page to one theme.

1<!-- 1. FOUC prevention: runs immediately, reads the stored theme from the cookie,2				and writes the theme class, data-theme, and data-applied-theme onto <html>.3				Generated by: preventWrongThemeFlashScriptContent() from "@ngrok/mantle/theme" -->4<script nonce="...">⋯5	(function z({ storageKey: e, themeByCookieValue: t, forceTheme: n }) {6		let r = `system`;7		try {8			let n = document.cookie9					.split(`;`)10					.map((e) => e.trim())11					.find((t) => t.startsWith(`${e}=`)),12				i = decodeURIComponent(n?.slice(e.length + 1) ?? ``);13			Object.hasOwn(t, i) && (r = t[i] ?? `system`);14		} catch {}15		let i = matchMedia(`(prefers-color-scheme: dark)`).matches ? `dark` : `light`;16		n == null ? r !== `system` && (i = r) : (i = n);17		let a = document.documentElement;18		(a.classList.remove(`light`, `dark`),19			a.classList.add(i),20			(a.dataset.theme = r),21			(a.dataset.appliedTheme = i));22	})({23		storageKey: "mantle-ui-theme",24		themeByCookieValue: {25			system: "system",26			light: "light",27			dark: "dark",28			"light-high-contrast": "light",29			"dark-high-contrast": "dark",30		},31	});32</script>

Usage

Drop in ThemeSwitcher for a one-click light/dark toggle:

1import { ThemeSwitcher } from "@ngrok/mantle/theme-switcher";2 3<ThemeSwitcher />;

To build your own control, read and set the preference with the useTheme hook:

1import { Select } from "@ngrok/mantle/select";2import { $theme, isTheme, useTheme } from "@ngrok/mantle/theme";3import { SunIcon } from "@phosphor-icons/react/Sun";4 5function App() {⋯6	const [currentTheme, setTheme] = useTheme();7 8	return (9		<Select.Root⋯10			value={currentTheme}11			onValueChange={(value) => {⋯12				if (isTheme(value)) {⋯13					setTheme(value);14				}15			}}16		>17			<Select.Trigger className="w-min" aria-label="Theme">⋯18				<SunIcon className="mr-1 h-6 w-6" />19			</Select.Trigger>20			<Select.Content>⋯21				<Select.Group>⋯22					<Select.Label>Choose a theme</Select.Label>23					<Select.Item value={$theme("system")}>System</Select.Item>24					<Select.Item value={$theme("light")}>Light</Select.Item>25					<Select.Item value={$theme("dark")}>Dark</Select.Item>26				</Select.Group>27			</Select.Content>28		</Select.Root>29	);30}

The theme swap

Every setTheme call that changes the applied theme runs the same swap as ThemeSwitcher: the new theme grows in a circle over the old one in a view transition. Pass origin to grow the circle from the control the user pressed. When you omit it, the circle grows from the focused element, else from the center of the viewport. Under prefers-reduced-motion: reduce, or in a browser without view transitions, the theme changes at once.

1const [, setTheme] = useTheme();2 3<Button type="button" onClick={(event) => setTheme("dark", { origin: event.currentTarget })}>⋯4	Use Dark theme5</Button>;

When the next theme depends on the current one, pass an updater, such as (theme) => (theme === "dark" ? "light" : "dark"). It reads the latest theme, even when a second press comes before the first swap runs. A dialog overlay or a dropdown menu that closes in the same press leaves at once, so it does not freeze under the circle.

High contrast

Mantle no longer ships high-contrast themes. A user who picked one in an earlier version keeps the base theme it was built on: a stored light-high-contrast reads as light, and dark-high-contrast reads as dark. ThemeProvider rewrites the old cookie value on mount, so every app on the cookie's domain agrees. An OS high-contrast setting (prefers-contrast: more) no longer changes the theme; "system" follows prefers-color-scheme alone.

Inverted theme islands

Add the invert-theme class to any element to render that subtree in the opposite theme of the page: light ⇄ dark. The island is styled by the opposite theme's own definitions, so every mantle component and color token inside it just works: no conditional rendering, no per-component overrides.

1import { Button } from "@ngrok/mantle/button";2 3<aside className="invert-theme bg-base text-strong rounded-2xl p-4 shadow-lg">⋯4	<p>This panel renders dark on light pages, light on dark pages.</p>5	<Button appearance="filled" intent="neutral">⋯6		Save7	</Button>8</aside>;

Sandbar is built on this: its floating panel is an invert-theme island, which is why the bar and its buttons always read inverted from the page in both themes.

How it works: every mantle color utility resolves a CSS custom property at the element that uses it, and custom properties inherit, so each theme's definitions are also applied directly to .invert-theme elements on the opposite theme's pages, re-declaring the theme variables where they win over the values inherited from :root.

Things to know:

• Portals escape the island. Floating content that portals to <body> (dropdown menus, tooltips, dialogs, …) renders in the page theme. Pass invert-theme in the floating part's className to invert it too.
• Theme variant utilities do not flip. dark:* and light:* key off the page theme on <html>, not the inversion scope; this applies to your own utilities as much as to mantle's. Four mantle internals still carry small variant-gated tweaks (Progress Bar, Progress Donut, Skeleton, Table). Avoid composing those inside an island until they migrate to theme-declared tokens.
• Rebrand at the ramp, not the alias. Islands re-declare the semantic aliases (--color-accent-*, --color-danger-*, …) on themselves so they re-resolve against the inverted ramps, and a declaration on the element beats an inherited value. Override --color-sky-600 rather than --color-accent-600 and the change flows into islands too.
• Nesting is idempotent. An invert-theme inside an inverted subtree stays inverted relative to the page; it does not revert to the page theme.
• Rebranding a ramp does not reach islands. An island restores mantle's pinned Tailwind defaults, so a consumer @theme palette override applies to the page but not inside an island. Closing that would need a shadow copy of every ramp under a second name.
• Shadows flip with the island. Shadow utilities resolve the shadow tokens at the element that uses them, and islands re-declare those tokens, so content inside a light island gets light-theme shadows, keeping the island's interior coherent.

Locking a page to one theme

forceTheme is not one prop: it's the same value passed to each piece that writes the theme class on <html>:

• PreventWrongThemeFlashScript, before first paint
• ThemeProvider, after mount
• useInitialHtmlThemeProps, in the server-rendered markup

mantle.css holds both themes. If one writer resolves the stored preference instead of the forced theme, it puts class="dark" on a forceTheme="light" page, :root.dark outranks the light base, and the page paints dark. Pass the same value everywhere:

1// root.tsx2const FORCED_THEME = "light" as const;3 4export default function Root() {⋯5	const htmlProps = useInitialHtmlThemeProps({ forceTheme: FORCED_THEME, ssrCookie });6 7	return (8		<html {...htmlProps}>⋯9			<head>⋯10				<PreventWrongThemeFlashScript forceTheme={FORCED_THEME} nonce={nonce} />11			</head>12			<body>⋯13				<ThemeProvider forceTheme={FORCED_THEME} ssrCookie={ssrCookie}>⋯14					<App />15				</ThemeProvider>16			</body>17		</html>18	);19}

The stored preference is still read, and setTheme still writes it, so other pages honor the user's choice. Only what this page paints is pinned: data-applied-theme and the class are the forced theme, while data-theme remains the preference. useAppliedTheme returns the forced theme, and ThemeSwitcher is disabled, because a click cannot change what this page paints.

That divergence is safe by construction. Every theme block guards its data-theme selector with :not([data-applied-theme]), so once anything applies a theme, the preference stops selecting one. Set data-theme on its own and it still picks the theme, exactly as before.

Testing and automation

The theme preference lives in the mantle-ui-theme cookie. ThemeProvider reads the cookie again and applies its theme to <html> on mount, when the tab becomes visible, on pageshow, when another tab changes the theme, and when the OS color scheme changes. ThemeProvider does not read the <html> class, so the next theme change replaces a direct edit to it.

To test a theme in a browser automation script, set the cookie, then reload:

1await context.addCookies([⋯2	{ name: "mantle-ui-theme", value: "dark", url: "http://localhost:3000" },3]);4await page.reload();

API Reference

ThemeProvider

The ThemeProvider accepts the following props in addition to the PropsWithChildren.

The ThemeProvider uses a hardcoded storage key of mantle-ui-theme and defaults to system theme. The provider manages both values internally, so they need no configuration.

PreventWrongThemeFlashScript

The PreventWrongThemeFlashScript component renders the inline script to prevent FOUC. Place it as early as possible in <head>. It accepts the following props:

preloadFontLink

Preferred for SSR. Returns an HTTP Link header value that preloads a single core font by name. This is the server-side equivalent of PreloadFont — identical in effect, but delivered as an HTTP header so the browser can start the font fetch before it has parsed any HTML, giving better CWV scores on mobile and slow connections.

1import { assetsCdnOrigin, preloadFontLink } from "@ngrok/mantle/theme";2 3// In your server entry (e.g. entry.server.tsx):4headers.set(5	"Link",6	[⋯7		`<${assetsCdnOrigin}>; rel=preconnect; crossorigin`,8		preloadFontLink("roobert"),9		preloadFontLink("jetbrains-mono"),10	].join(", "),11);

Returns: A Link header value string, e.g. <https://assets.ngrok.com/fonts/roobert/roobert-proportional-vf.woff2>; rel=preload; as=font; type="font/woff2"; crossorigin.

PreloadFont

The PreloadFont component renders a single preload <link> element for one named core font. Prefer preloadFontLink in SSR apps where you can set HTTP response headers — sending the hint as a header starts the fetch earlier than HTML parsing allows. Use PreloadFont when you have no access to response headers.

1import { PreloadFont } from "@ngrok/mantle/theme";2 3<head>⋯4	<PreloadFont name="roobert" />5	<PreloadFont name="jetbrains-mono" />6</head>;

CoreFontName values:

extractThemeCookie

Extracts only the theme cookie key-value pair from a full Cookie header string. Pass the result to ThemeProvider and useInitialHtmlThemeProps as ssrCookie. This keeps the other cookies from the request out of loader data.

1import { extractThemeCookie } from "@ngrok/mantle/theme";2 3// In your root loader:4const ssrCookie = extractThemeCookie(request.headers.get("Cookie"));5// e.g. "mantle-ui-theme=dark" or undefined

Returns: The mantle-ui-theme=<value> pair as a string, or undefined if the cookie is not present.

useInitialHtmlThemeProps

The useInitialHtmlThemeProps hook returns props that should be applied to the <html> element to prevent React hydration errors. It accepts the following options:

Returns: An object with className, data-theme, and data-applied-theme props to spread onto your <html> element.

On the server, when ssrCookie is set, the hook reads the theme from the cookie to render the correct class. When omitted, it defaults to system theme (resolved to light). On the client, it reads the current theme from document.cookie to match what the FOUC prevention script applied, so React hydration succeeds.