API Reference
@themvora/solid
Solid provider, signals and scopes with fine-grained reactivity.
Provides the ThemeProvider, ThemeScope, ThemeScrollbar, and
ThemeInspector components, the useTheme* hooks, and the SSR
bootstrap-script helper.
Generated from
packages/solid/srcbyapps/docs/scripts/generate-api-reference.mjs. Do not edit by hand — runpnpm --filter @themvora/docs api:generate.
Functions
createSolidThemeBootstrapScript<T extends ThemeDefinition<string>>(options): string
Build the blocking zero-flash <head> script for a SolidJS app (SSR or SPA).
Inlines core's createThemeBootstrapScript with the Solid defaults
(storageKey: "theme-selection", prefix: "theme-" — the same values the
Solid ThemeProvider persistence and CSS variables use), so the persisted
theme is applied before first paint. Emit the returned string as a
blocking <script> inside <head>.
See also: createThemeBootstrapScript
| Parameter | Type | Description |
|---|---|---|
options | ThemeBootstrapScriptOptions<T> | — |
Returns string
ThemeInspector(props): Element
Renders the floating theme inspector for the active runtime.
Defines and mounts the <themvora-inspector> custom element, forwarding the
given position, size, z-index, class, and style props. The inspector
reads the active theme from the runtime and lets users inspect and switch
themes at runtime.
See also: ThemeProvider, useTheme
| Parameter | Type | Description |
|---|---|---|
props | ThemeInspectorProps | The inspector configuration. |
Returns Element
ThemeProvider<T extends ThemeDefinition<string>>(props): Element
Provides a ThemeRuntime to the Solid component tree via context.
When no runtime prop is given the provider creates and owns a runtime from
the remaining ThemeProviderProps (which extend
ThemeRuntimeOptions), wiring up DOM and CSS-variable bindings on
mount and destroying the runtime on cleanup. When a runtime prop is
supplied the provider adopts that caller-owned runtime and does not destroy
it. Renders no DOM of its own — it only supplies context to its children.
See also: useTheme, ThemeScope, useThemeRuntime
| Parameter | Type | Description |
|---|---|---|
props | ThemeProviderProps<T> | The provider options and children. |
Returns Element
The provider must be mounted before any hook that reads the runtime
(useTheme, useThemeRuntime, …) is called, since those hooks throw when
no provider context exists. On the server the provider renders its children
without DOM bindings; the persisted selection is applied client-side before
first paint via an injected bootstrap script.
import { ThemeProvider } from "@themvora/solid";
function App() {
return (
<ThemeProvider defaultTheme="light">
<YourApp />
</ThemeProvider>
);
}ThemeScope(props): Element
Creates a nested theme boundary that overrides the selection for its subtree.
Renders a wrapper <div> carrying the resolved theme's data-theme,
data-mode, and CSS-variable inline styles, and keeps it in sync as the
scope's props or the provider's selection change. On the server no wrapper
is rendered — the children are returned directly so the provider's :root
attributes apply client-side.
See also: ThemeProvider, useTheme
| Parameter | Type | Description |
|---|---|---|
props | ThemeScopeProps | The scope configuration and children. |
Returns Element
The scope does not create a second runtime; it resolves against the
provider's theme registry, with any themes prop shadowing same-named
parent themes. Family-based and boundary-only scopes follow the provider's
live mode, flipping light/dark when the global mode changes.
ThemeScrollbar(props): null
Applies an overlay scrollbar to the runtime's scrollable content.
Installs an overlay scrollbar bound to the active theme's store on mount and
destroys it on cleanup. Renders no DOM of its own — it returns null and
only manages the scrollbar lifecycle for the surrounding content.
See also: ThemeProvider
| Parameter | Type | Description |
|---|---|---|
props | ThemeScrollbarProps | The scrollbar options and children. |
Returns null
useEffectiveThemeMode(): Accessor<"light" | "dark">
Reactive access to the mode actually applied — "light" or "dark",
never "system" — as a Solid signal.
Render this when a control states the current appearance. useThemeMode
reports what the visitor asked for: it stays "system" while that choice
stands and it does not move at a sunrise/sunset transition, so a label bound
to it kept announcing the old mode while the page changed colour.
See also: useThemeMode, useThemeSchedule
Returns Accessor<"light" | "dark"> — A Solid signal holding the applied mode.
useGeneratedTheme<T extends ThemeDefinition<string>>(): Accessor<T>
Reactive access to the theme produced by generateTheme() and registered
with the provider, as a Solid signal.
Resolves the registered theme that carries the generator's origin marker
(meta.generation.kind === "generated"); shipped presets never qualify. When
both halves of one generateTheme() call are registered, the signal tracks
the theme the active selection resolves to. The subscription is disposed on
component cleanup.
Throws ThemeError with code TV_GENERATION_THEME_NOT_FOUND when the provider
holds no generated theme, and TV_GENERATION_THEME_AMBIGUOUS when several are
registered and the active selection does not identify one.
Re-resolves on every settled change to the registry, store, or selection; if the generated theme is later removed, the same error is raised at the next reactive read rather than a stale theme being returned.
See also: useThemeValue
Returns Accessor<T> — A Solid signal holding the registered generated theme.
useProvidedThemes<T extends ThemeDefinition<string>>(): Accessor<readonly ProvidedThemeFamily<T>[]>
Reactive access to the themes this provider was given, grouped by family.
Returns exactly the collection supplied to the nearest ThemeProvider — not
the built-in catalog. The accessor tracks the provider's registry, so a
themes prop change, a theme-pack install or a registry mutation re-runs
every consumer of it, and the array instance is stable while nothing changes.
const families = useProvidedThemes();
<For each={families()}>{(family) => <h3>{family.name}</h3>}</For>See also: useThemeValue
Returns Accessor<readonly ProvidedThemeFamily<T>[]> — An accessor holding the provider's theme families.
useTheme<T extends ThemeDefinition<string>>(): { effectiveMode: Accessor<"light" | "dark">; family: Accessor<string>; mode: Accessor<ThemeMode>; setFamily: __type(nextFamily: string): void; setMode: __type(nextMode: ThemeMode): void; theme: Accessor<T>; toggleTheme: __type(): void }
Reactive access to the current theme selection plus actions to change it.
Combines the reactive signals from useThemeValue, useThemeMode,
useEffectiveThemeMode and useThemeFamily with imperative setters that drive
the runtime selection. Must be called inside a component rendered within a
ThemeProvider.
mode is the visitor's request; effectiveMode is what is on screen — they
differ while a sunrise/sunset schedule runs, or while the selection is
"system".
See also: useThemeValue, useThemeMode, useEffectiveThemeMode, useThemeFamily
Returns { effectiveMode: Accessor<"light" | "dark">; family: Accessor<string>; mode: Accessor<ThemeMode>; setFamily: __type(nextFamily: string): void; setMode: __type(nextMode: ThemeMode): void; theme: Accessor<T>; toggleTheme: __type(): void } — An object with reactive theme, mode, effectiveMode and family
signals and the setMode, setFamily, and toggleTheme actions.
import { useTheme } from "@themvora/solid";
function ThemeToggle() {
const { effectiveMode, toggleTheme } = useTheme();
return (
<button onClick={toggleTheme}>
Current mode: {effectiveMode()}
</button>
);
}useThemeBatch(): __type(callback: __type(): void): void
Returns a function that batches multiple runtime mutations into a single store update.
The returned callback forwards to the runtime's batch method, coalescing
several selection changes so subscribers observe one consolidated change.
See also: useThemeRuntime, useTheme
Returns __type(callback: __type(): void): void — A function accepting a callback whose mutations are batched.
useThemeFamily(): Accessor<string>
Reactive access to the current theme family as a Solid signal.
Returns a signal tracking the runtime selection's theme family name. The signal is seeded on mount and kept in sync with the store; the subscription is disposed on component cleanup.
See also: useTheme
Returns Accessor<string> — A Solid signal holding the current theme family name.
useThemeHistory<T extends ThemeDefinition<string>>(): { clear: __type(): void; jump: __type(index: number): void; redo: __type(): void; undo: __type(): void; canRedo: void; canUndo: void; history: void }
Reactive access to the runtime's theme history (undo/redo).
Returns reactive canUndo, canRedo, and history getters plus the
undo, redo, clear, and jump actions. The reactive state is seeded on
mount and refreshed whenever the store changes; the subscription is disposed
on component cleanup.
See also: useThemeRuntime, useThemeBatch
Returns { clear: __type(): void; jump: __type(index: number): void; redo: __type(): void; undo: __type(): void; canRedo: void; canUndo: void; history: void } — An object exposing the history state and navigation actions.
useThemeLifecycle(): { on: __type(event: keyof ThemeLifecycleEventMap<ThemeDefinition<string>>, listener: __type(data: unknown): void): __type(): void }
Returns a function that subscribes to runtime lifecycle events.
The returned on callback forwards to the runtime's lifecycle emitter,
registering a listener for the given ThemeLifecycleEventName.
See also: useThemeRuntime, useTheme
Returns { on: __type(event: keyof ThemeLifecycleEventMap<ThemeDefinition<string>>, listener: __type(data: unknown): void): __type(): void } — An object exposing an on function to register lifecycle listeners.
useThemeMode(): Accessor<ThemeMode>
Reactive access to the current theme mode as a Solid signal.
Returns a signal tracking the runtime selection's mode (light, dark, or
system). The signal is seeded on mount and kept in sync with the store;
the subscription is disposed on component cleanup.
See also: useTheme
Returns Accessor<ThemeMode> — A Solid signal holding the current theme mode.
useThemePacks(): __type(pack: ThemePack<any>): void
Returns a function that installs a theme pack onto the runtime.
The returned callback forwards to the runtime's use method, registering a
ThemePack so its themes become available to the selection.
See also: useThemeRuntime, useTheme
Returns __type(pack: ThemePack<any>): void — A function accepting a theme pack to install.
useThemeRestore(): __type(snapshot: ThemeRuntimeSnapshot): void
Returns a function that restores the runtime from a previously captured snapshot.
The returned callback forwards to the runtime's restore method, applying
the given ThemeRuntimeSnapshot back onto the runtime.
See also: useThemeSnapshot
Returns __type(snapshot: ThemeRuntimeSnapshot): void — A function accepting a snapshot to restore.
useThemeRuntime<T extends ThemeDefinition<string>>(): ThemeRuntime<T>
Returns the active ThemeRuntime from the nearest ThemeProvider.
Must be called inside a component (owner) rendered within a ThemeProvider;
otherwise it throws. The returned runtime is the same object the provider
owns or adopts, so it is not reactive by itself — use the dedicated hooks
(useThemeValue, useThemeMode, …) for reactive reads.
See also: ThemeProvider, useThemeValue
Returns ThemeRuntime<T> — The active theme runtime.
useThemeSchedule<T extends ThemeDefinition<string>>(): { disable: __type(): void; enable: __type(): void; set: __type(options: ThemeScheduleSetOptions): void; active: void; darkTheme: void; enabled: void; lightTheme: void; nextActivation: void; nextDeactivation: void; nextTransition: void; status: void; sunrise: void; sunset: void } | null
Reactive access to the runtime's sunrise/sunset scheduling controller.
Returns null when the provider was created without the scheduled option.
Reads of enabled/active/status/sunrise/sunset/nextTransition
track the underlying state reactively.
const schedule = useThemeSchedule();
schedule?.enable();
schedule?.disable();Returns { disable: __type(): void; enable: __type(): void; set: __type(options: ThemeScheduleSetOptions): void; active: void; darkTheme: void; enabled: void; lightTheme: void; nextActivation: void; nextDeactivation: void; nextTransition: void; status: void; sunrise: void; sunset: void } | null
useThemeSnapshot(): __type(): ThemeRuntimeSnapshot<ThemeDefinition<string>>
Returns a function that captures the runtime's current state as a snapshot.
The returned callback forwards to the runtime's snapshot method, producing
a ThemeRuntimeSnapshot that can later be passed to useThemeRestore.
See also: useThemeRestore
Returns __type(): ThemeRuntimeSnapshot<ThemeDefinition<string>> — A function returning the current runtime snapshot.
useThemeTokens<T extends ThemeDefinition<string>>(): Accessor<ThemeTokens | undefined>
Reactive access to the active theme's token group as a Solid signal.
Returns a signal whose value is the tokens object of the current theme
selection, or undefined when the active theme defines no tokens. The
signal updates whenever the store's theme changes and the subscription is
disposed on component cleanup.
See also: useThemeValue
Returns Accessor<ThemeTokens | undefined> — A Solid signal holding the active theme's tokens.
useThemeValue<T extends ThemeDefinition<string>>(): Accessor<T>
Reactive access to the current theme selection as a Solid signal.
Returns a signal whose value tracks the runtime store's active theme. The signal is seeded from the store on mount and updated on every store change; the subscription is disposed automatically when the owning component is cleaned up.
See also: useTheme, useThemeRuntime
Returns Accessor<T> — A Solid signal holding the active theme.
Interfaces
ThemeInspectorProps
Props accepted by ThemeInspector.
Configures the floating theme inspector's position, size, and z-index, plus
optional class and style forwarded to the underlying
<themvora-inspector> element.
| Member | Type | Description |
|---|---|---|
bottom (optional) | number | Distance from the bottom of the viewport, in px. Default 104. |
class (optional) | string | Forwarded to the underlying <themvora-inspector> element. |
right (optional) | number | Distance from the right edge of the viewport, in px. Default 32. |
size (optional) | number | Toggle button size, in px. Default 40. |
style (optional) | string | Inline styles forwarded to the underlying <themvora-inspector> element. |
zIndex (optional) | number | Z-index for the floating toggle and panel. Default 9999. |
ThemeProviderProps<T extends ThemeDefinition>
Extends ThemeRuntimeOptions<T>
Props accepted by ThemeProvider.
Extends ThemeRuntimeOptions so the provider can build and own a
runtime from the same options used by createThemeRuntime. When runtime
is supplied the provider adopts that caller-owned runtime instead of
creating one.
| Member | Type | Description |
|---|---|---|
adapters (optional) | ThemeAdapter<T>[] | Library adapters installed when the runtime is created. The runtime owns the registry and notifies every adapter whenever the theme changes; it never knows anything about the libraries themselves. |
broadcast (optional) | ThemeSelectionBroadcastAdapter | null | Cross-tab broadcast adapter. When omitted, a BroadcastChannel-based adapter on channel "theme-selection" is created; pass null to disable cross-tab sync. |
children (optional) | Element | The subtree rendered inside the provider's context. |
cssVariables (optional) | false | CSSVariablesOptions | CSS-variable binding configuration. false disables the binding. |
defaultTheme (optional) | ThemeIdentifier<T> | Theme to activate when no persisted or explicit selection exists. Accepts a variant name ("cocoa-dark") or a family name ("cocoa"); a family resolves to the variant the mode contract picks (see resolveThemeReference). A variant also supplies its own mode unless initialMode is given. |
dom (optional) | false | DOMBindingOptions | DOM attribute/class binding configuration. false disables the binding. |
initial (optional) | InitialThemeResolution<T> | Explicit initial theme resolution, bypassing default + persistence based resolution. |
initialFamily (optional) | ThemeIdentifier<T> | Initial family used when nothing else is given. A variant name is also accepted and normalised to its family; the variant's own mode is used only when initialMode is absent, so an explicit mode always wins and the two props cannot silently disagree. |
initialMode (optional) | ThemeMode | Initial mode used when nothing else is given. |
persistence (optional) | ThemeSelectionPersistenceAdapter | null | Persistence adapter for the theme selection. Pass null to disable persistence entirely. |
plugins (optional) | ThemePlugin<T>[] | Runtime plugins installed at creation. |
readPersistenceOnInit (optional) | boolean | Whether a persisted selection is read at runtime creation. |
runtime (optional) | ThemeRuntime<T> | An existing runtime to adopt. When omitted the provider creates and owns its own runtime from the remaining props. |
scheduled (optional) | false | ScheduledThemeOptions<T> | Sunrise/sunset scheduling configuration. false disables scheduling. |
themeOverride (optional) | ThemeOverride<ThemeIdentifier<T>> | An explicit theme to apply, outranking a saved selection. Unlike defaultTheme, which is only a fallback, an override is applied even when localStorage or a cookie already names another theme — which is what makes "preview this theme" expressible as a prop. It is a one-shot signal, not a controlled selection: it is applied when its value changes, it is never re-asserted on later renders, and it does not write to persistence. See ThemeOverride. |
themes (optional) | readonly T[] | Initial theme definitions. Duplicate names are dropped (first wins). When omitted, the registry starts empty. |
transition (optional) | boolean | ThemeTransitionOptions | Transition configuration. true enables transitions with defaults, false disables them, and an object provides explicit options. |
view (optional) | Window | The window to bind to. Defaults to the global window when available; omit (or pass undefined) in SSR environments. |
ThemeScopeProps
Props accepted by ThemeScope.
Configures a nested theme boundary that overrides the global selection for
its subtree. theme wins over family/mode; when none are given the
scope mirrors the provider's selection inside its own boundary.
| Member | Type | Description |
|---|---|---|
children (optional) | Element | The subtree rendered inside the scope's wrapper. |
className (optional) | string | CSS class applied to the scope's wrapper <div>. |
family (optional) | string | Theme family for the scoped subtree. When mode is omitted the scope follows the provider's current mode (light/dark/system). |
mode (optional) | ThemeMode | Mode for a family-based scope. Optional — defaults to the provider's current mode so family="plum" flips light/dark with the page. |
theme (optional) | string | Exact theme name, family name, or a { family, mode }-style object. When family/mode are also passed, theme wins (it's the explicit selection). Omit to follow the global selection inside a new boundary. |
themes (optional) | readonly ThemeDefinition<string>[] | Local theme definitions for genuinely isolated components. Resolved FIRST (they shadow same-named parent themes), then the provider's registry falls back — no second runtime is created. |
transition (optional) | boolean | ThemeTransitionOptions | Transition for this scope's own theme changes. undefined inherits the <ThemeProvider/> transition, false disables it, true inherits, and an object is merged over the provider's config (local keys win). |
ThemeScrollbarProps
Extends ScrollbarGroupedOptions
Props accepted by ThemeScrollbar.
Extends OverlayScrollbarOptions so the scrollbar can be configured
with the same options used by createOverlayScrollbar.
| Member | Type | Description |
|---|---|---|
appearance (optional) | ScrollbarAppearanceOptions | — |
behavior (optional) | ScrollbarBehaviorOptions | Grouped settings - the canonical form; a flat option wins over it. |
children (optional) | Element | The subtree the scrollbar is applied to. |
icons (optional) | ScrollbarIconOptions<string> | Arrow button icons: the arrow entry covers all four directions (per-direction entries win), plus the shared glyph size in CSS px. |
scope (optional) | ScrollbarScopeOptions | — |
Related docs
- Families & Modes — A selection is a family (which palette) plus a mode (light/dark/system); every framework exposes the same read/write surface for it.
- 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.
- Persistence — Persist the selection across reloads and requests, with fingerprint validation, storage adapters and theme migrations.
- Theme generation — Generate a complete, accessible light/dark theme pair from a single seed color, ready to drop into the runtime.
- Plugins — Extend the runtime through a first-class plugin manager and adapter registry; theme packs install ready-made behaviour.
- Zero-flash bootstrap — Paint the correct theme on the first frame: a blocking script plus server-resolved initial state, with a Vite plugin for SPA builds.
- Custom scrollbar — Themed overlay scrollbars that match the active theme and pre-paint before hydration.
- DevTools — Inspect and drive the live runtime from a panel: adapters, history, snapshots and performance entries.
- Solid — the framework integration