@themvora/next

Provides the SSR-safe ThemeProvider (with ThemeProviderHtmlProps / ThemeProviderBodyProps for zero-flash layout wiring) plus the React ThemeScope and ThemeScrollbar re-exports.

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

Functions

ThemeProvider<T extends ThemeDefinition<string>>(props): Element

App Router theme provider. Must be used in the root layout: it renders the <html> and <body> elements, resolves the persisted selection, emits matching SSR CSS variables and a blocking bootstrap script, and mounts the client runtime inside the body.

See also: ThemeProviderProps, ThemeProviderBodyProps, ThemeProviderHtmlProps

Returns Element — The themed <html>/<body> tree wrapping the application content.

Because this component renders the document shell, it must be the root of the App Router layout tree. body props are forwarded to the <body> element; className/style are merged with the theme's SSR output.

The component itself is synchronous: the document shell is deterministic and request-independent. The persisted theme is resolved in a nested server component under <Suspense> (see ResolvedThemeProvider) and applied pre-paint by the blocking bootstrap, so the shell is never blocking under Next's Cache Components.

import { ThemeProvider } from "@themvora/next";

export default function RootLayout({ children }) {
  return (
    <ThemeProvider defaultTheme="light" scrollbar>
      {children}
    </ThemeProvider>
  );
}

ThemeScope(__namedParameters): Element

Applies a theme to a subtree without replacing the global runtime.

The scope resolves local themes (themes prop) before falling back to the parent runtime's theme registry. Nested scopes override their parent within their own boundary. Theme changes are reactive: theme/family/mode props and global mode changes re-resolve and animate in place without remounting.

See also: useScopedTheme

Returns Element

Scope-local transitions inherit the parent transition configuration unless explicitly overridden or disabled. First paint is server-safe: explicit selections ship resolved variables inline, while OS-dependent selections (system mode / family-following scopes) ship no inline variables plus a @media (prefers-color-scheme: dark) override, so no flash occurs.

<ThemeScope family="plum" mode="dark">
  <Editor />
</ThemeScope>

ThemeScrollbar(props): null

ThemeScrollbar — overlay only.

Creates the custom scrollbar overlay.

Lifecycle: mount → create overlay → measure → attach listeners paint → add tv-scrollbar-ready destroy → remove overlay

Props are four optional groups — behavior, appearance, scope and icons — plus children, which is accepted for JSX symmetry only.

<ThemeScrollbar behavior={{ autoHide: true, smooth: true }} appearance={{ thickness: 8, radius: 999 }} scope={{ include: [".panel"] }} icons={{ up: <ArrowUpIcon />, size: 12 }} />

<ThemeScrollbar behavior={{ autoHide: true, smooth: true }} appearance={{ thickness: 8, radius: 999 }} icons={{ up: <ArrowUpIcon />, down: <ArrowDownIcon /> }} />

See also: ThemeProvider

Returns null

Interfaces

ThemeProviderBodyProps

Extends Omit<HTMLAttributes<HTMLBodyElement>, "children" | "className" | "style"> Attributes forwarded to the rendered <body> element. className and style are merged with the theme's SSR output (the resolved font family is applied to the body) rather than replaced.

See also: ThemeProvider

ThemeProviderHtmlProps

Extends Omit<HTMLAttributes<HTMLHtmlElement>, "children" | "lang" | "className" | "style"> Every attribute a plain <html> element accepts, You can pass straight through to ThemeProvider. className and style are merged with the theme's SSR output rather than replaced.

See also: ThemeProvider

ThemeProviderProps<T extends ThemeDefinition>

Extends ThemeProviderHtmlProps Props for the App Router ThemeProvider. Renders the <html> and <body> elements, applies the theme, and mounts the client runtime inside the body.

See also: ThemeProvider, ThemeProviderBodyProps

The document shell is static; the persisted selection resolves behind a Suspense boundary. ThemeProvider renders <html>/<head>/<body> from the configured themes/defaultTheme alone — it never awaits request data — so a route that hosts it stays prerenderable under Next's Cache Components with no route-segment opt-out (in particular no export const instant = false). The persisted, cookie-backed selection is resolved two ways that agree with each other:

• the blocking bootstrap script in <head> reads the same cookies in the browser and writes the selection onto <html> before the first frame, so the static default never flashes; and
• a nested server component under <Suspense> reads cookies() and hands the resolved selection to the client runtime, so the hydrated provider and the server-rendered subtree both carry the visitor's theme.

data-theme-selection-mode/-family are declared on the shell too: the script rewrites them, so React's hydration diff is suppressed on the document element — the narrowest scope that covers attributes the script owns.

import { ThemeProvider } from "@themvora/next";

export default function RootLayout({ children }) {
  return (
    <ThemeProvider defaultTheme="light" font="Inter, sans-serif">
      {children}
    </ThemeProvider>
  );
}

ThemeScopeProps

Props for the ThemeScope component.

Accepts theme (exact selection), family/mode (family-based selection), themes (scope-local definitions), and transition.

ThemeScrollbarProps

Props for the ThemeScrollbar overlay component.

Options are grouped into behavior, appearance, and icons — but every option is also accepted as a flat, top-level prop (flat props win over the grouped ones).

Related docs

• Theme Discovery & Overrides — A provider exposes exactly the themes it was given — grouped by family, with variants and resolved tokens — and accepts an explicit one-shot themeOverride that outranks a saved selection.
• Runtime — One runtime per app owns the store, selection, registry, history, lifecycle and adapters; every framework binding is a thin view over it.
• ThemeScope — Apply a different family/mode (or a local theme definition) to a subtree, with scoped CSS variables and pre-paint support.
• Custom scrollbar — Themed overlay scrollbars that match the active theme and pre-paint before hydration.
• Next.js — the framework integration