@themvora/web

Provides the custom elements ThemvoraProvider, ThemvoraScope, ThemvoraToggle, ThemvoraSelect, ThemvoraScrollbar, and ThemvoraInspector, plus the useTheme* hooks, getProviderRuntime, getThemeSchedule, and the defineCustomElements registration helper.

HTML-first usage

Importing this entry is enough: it registers the built-in elements and injects their stylesheet once, so the consumer writes semantic HTML and nothing else.

<themvora-provider themes="light dark plum-dark" default-theme="light">
  <themvora-toggle></themvora-toggle>
  <themvora-select type="family"></themvora-select>
  <themvora-scope theme="plum-dark">…</themvora-scope>
</themvora-provider>

import "@themvora/web";

Registration is idempotent and browser-only: importing the package during a server render is a no-op, so Next.js, Remix, Nuxt, Astro and SvelteKit can import it without a browser guard.

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

Functions

defineCustomElements(): void

Registers all Themvora custom elements with the browser and injects the built-in component stylesheet.

Framework-free (vanilla JS). Defines <themvora-provider>, <themvora-scope>, <themvora-toggle>, <themvora-select>, <themvora-scrollbar> and <themvora-inspector> if not already registered, and adds the component stylesheet once. Safe to call more than once, and a no-op on the server.

See also: ThemvoraProvider

Returns void

Importing @themvora/web already calls this, so a consumer normally never calls it. It stays public for two cases: a consumer who wants to register a different tag name (ThemvoraProvider.define("my-provider")), and a consumer who needs the registration to happen at a specific point rather than at module evaluation.

import { defineCustomElements } from "@themvora/web";
defineCustomElements();

getProviderRuntime(el?): ThemeRuntime<ThemeDefinition<string>> | undefined

Returns the Themvora runtime attached to a provider element, if any.

Framework-free (vanilla JS). Reads the runtime stored on the element by setProviderRuntime.

See also: findProviderRuntime, ThemvoraProvider

Returns ThemeRuntime<ThemeDefinition<string>> | undefined — The attached runtime, or undefined when none is present.

getThemeSchedule(): ThemeSchedule | null

Reactive sunrise/sunset schedule controller. Returns null when the provider was created without the scheduled option.

const schedule = getThemeSchedule();
schedule?.enable();
schedule?.disable();
schedule?.set({ timeZone: "Asia/Kathmandu" });

Returns ThemeSchedule | null

injectComponentStyles(): boolean

Injects COMPONENT_CSS into the document once.

Idempotent: repeated calls, duplicate bundle evaluation and a consumer who already pasted the stylesheet into their own <style id="themvora-elements-style"> all leave exactly one copy in the document. A no-op on the server.

Returns boolean — true when this call inserted the stylesheet, false when it was already present or the environment has no DOM.

injectPrePaintScrollbarCSS(): void

Injects the pre-paint scrollbar-hiding CSS and class into the document.

Framework-free (vanilla JS). Adds a <style> carrying the pre-paint scrollbar CSS and the tv-scrollbar class to the document root so the native scrollbar is hidden before first paint. Idempotent and a no-op on the server.

This is a manual bootstrap helper for a page that wants the native bar hidden before its own script runs. It is not how ThemvoraScrollbar hides the bar — that happens through createOverlayScrollbar, which claims the hiding and gives it back on destroy(). Calling this directly therefore hides the bar without registering a claim, so pair it with restoreNativeScrollbar() if you later want the native bar back.

See also: ThemvoraScrollbar

Returns void

observeEffectiveThemeMode(listener): __type(): void

Calls listener whenever the applied mode changes, and returns an unsubscribe function.

Framework-free (vanilla JS). Requires an initialized <themvora-provider>. The listener is not called once up front — read useEffectiveThemeMode for the current value and call it again from the listener.

const stop = observeEffectiveThemeMode(() => {
  label.textContent = useEffectiveThemeMode();
});

See also: useEffectiveThemeMode

Returns __type(): void — An unsubscribe function.

resolveGeneratedTheme<T extends ThemeDefinition<string>>(themes, active?): T

Resolve the single generated theme registered with a provider, or throw.

The throwing counterpart of findGeneratedTheme, for call sites that need a theme rather than a status — the framework accessors, which surface the failure to the caller.

See also: `- isGeneratedTheme

• findGeneratedTheme`

Returns T — The resolved generated theme.

useEffectiveThemeMode(): "light" | "dark"

Returns the mode actually applied — "light" or "dark", never "system".

Framework-free (vanilla JS). Requires an initialized <themvora-provider>.

Use 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.

Pair it with observeEffectiveThemeMode to re-render on change.

See also: useThemeMode, observeEffectiveThemeMode

Returns "light" | "dark" — The applied mode.

useGeneratedTheme(): ThemeDefinition<string>

Returns the theme produced by generateTheme() and registered with the active <themvora-provider>.

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 theme the active selection resolves to is returned.

Framework-free (vanilla JS). Requires an initialized <themvora-provider>.

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.

Reads live on every call, so a theme removed from the registry is reported immediately rather than a stale value being returned.

See also: useThemeValue

Returns ThemeDefinition<string> — The registered generated theme.

useProvidedThemes(): readonly ProvidedThemeFamily<ThemeDefinition<string>>[]

Returns the themes the active <themvora-provider> was given, grouped by family.

Framework-free (vanilla JS). Reads live on every call, so a theme registered after the provider initialized appears immediately — the vanilla surface has no reactive wrapper by design, matching useThemeValue. For a push notification, listen for the provider's themes-change event.

const families = useProvidedThemes();
families.forEach((family) => {
  console.log(family.family, family.variants.map((v) => v.mode));
});

See also: useThemeRuntime, normalizeProvidedThemes

Returns readonly ProvidedThemeFamily<ThemeDefinition<string>>[] — The provider's theme families, in supplied order.

useThemeFamily(): string

Returns the current theme family.

Framework-free (vanilla JS). Requires an initialized <themvora-provider>.

See also: useThemeRuntime, defineCustomElements

Returns string — The current theme family.

useThemeMode(): ThemeMode

Returns the current theme mode (system, light, or dark).

Framework-free (vanilla JS). Requires an initialized <themvora-provider>.

See also: useThemeRuntime, defineCustomElements

Returns ThemeMode — The current mode.

useThemeRuntime(): ThemeRuntime<ThemeDefinition<string>>

Resolves the active Themvora runtime from the first initialized <themvora-provider> in the document.

Framework-free (vanilla JS). Must be called after a <themvora-provider> has initialized.

Multiple providers: this returns the first provider in document order that has a runtime. It is a page-level convenience, not a way to address a specific provider — use getProviderRuntime(element) when more than one provider exists, or when the element you hold is not the first.

See also: getProviderRuntime, defineCustomElements

Returns ThemeRuntime<ThemeDefinition<string>> — The provider's runtime.

const runtime = useThemeRuntime();
runtime.selection.setMode("dark");

useThemeTokens(): ThemeTokens | undefined

Returns the active theme's token group from the active runtime.

Framework-free (vanilla JS). Requires an initialized <themvora-provider>.

See also: useThemeRuntime, defineCustomElements

Returns ThemeTokens | undefined — The active theme's tokens.

useThemeValue(): ThemeDefinition<string>

Returns the currently selected theme definition from the active runtime.

Framework-free (vanilla JS). Requires an initialized <themvora-provider>.

See also: useThemeRuntime, defineCustomElements

Returns ThemeDefinition<string> — The active theme definition.

Classes

class ThemvoraInspector

Extends ThemvoraRuntimeConsumer Custom element <themvora-inspector> that inspects the active theme.

Framework-free (vanilla JS). Renders a floating toggle that opens a panel showing the active theme's identity, selection, tokens, and resolved CSS variables, updating live as the theme changes. Observes the bottom, right, size, and z-index attributes.

See also: defineCustomElements, ThemvoraProvider

Attributes. All four are positional and optional:

• bottom — distance from the bottom of the viewport, in px (default 104).
• right — distance from the right edge, in px (default 32).
• size — toggle button size, in px (default 40).
• z-index — stacking order of the toggle and panel (default 9999).

Non-numeric values are ignored in favour of the default.

Properties. None of its own beyond the standard HTMLElement surface.

Events. Dispatches nothing of its own.

Slots. None — the panel is built from the runtime's data.

Requires an ancestor <themvora-provider>. If the provider is not yet initialized, it waits for the theme-ready event. define() is SSR-safe and no-ops when customElements is unavailable.

<themvora-inspector bottom="24" right="24"></themvora-inspector>

class ThemvoraProvider

Extends CustomElementBase Custom element <themvora-provider> that owns a Themvora runtime and applies the active theme to the document.

Framework-free (vanilla JS). Creates and destroys its runtime across its lifecycle, applies DOM/CSS variable bindings, and dispatches a bubbling theme-ready event once initialized. Observes the themes, default-theme, initial-mode, initial-family, scheduled, and transition attributes.

See also: ThemvoraProviderProps, defineCustomElements, ThemvoraScope, ThemvoraToggle, ThemvoraSelect

Attributes. All six are observed and applied to the live runtime.

• themes — the catalog. Either space-separated registered identifiers ("light dark plum-light") or a JSON array of full theme definitions ('[{"name":"brand","tokens":{…}}]'). An unknown identifier is reported and skipped; an empty or unusable list falls back to the neutral light/dark pair (TV_THEME_NEUTRAL_FALLBACK).
• default-theme — theme name used when nothing is persisted. Supplies both the fallback theme's family and its mode; an unknown name resolves to the catalog's first theme.
• initial-mode — "light", "dark" or "system" (case-insensitive). Overrides the mode default-theme implies. An invalid value is reported (TV_CONFIG_OPTION_INVALID) and ignored.
• initial-family — family used when nothing is persisted. Overrides the family default-theme implies; an unregistered one is reported (TV_THEME_FAMILY_UNKNOWN) and normalised.
• transition — true, false, or JSON ('{"enabled":true,"duration":250,"easing":"ease-in-out"}'). Changing it reconfigures the live bindings; removing it returns to no transition.
• scheduled — JSON sunrise/sunset options ('{"latitude":27.7,"longitude":85.3}'). Removing it tears the schedule down.

Properties. None of its own beyond the standard HTMLElement surface. The runtime is reached with getProviderRuntime (or useThemeRuntime for the first provider on the page).

Events. theme-ready (bubbles, composed) once the runtime exists and the first theme is applied; themes-change (bubbles, composed) on a microtask after the catalog changes, with detail.themes holding the new names.

Slots. Its children are ordinary light-DOM content — the consumer's markup and the other <themvora-*> elements. The element renders no wrapper and styles nothing of its own.

When an observed attribute changes after initialization, the change is applied to the live runtime through the shared configure() contract — the runtime is never destroyed and recreated, so history, persistence and the current selection survive, and the transition/schedule subsystems are reconciled in place.

Removing an attribute never resets the runtime. A removed themes, default-theme, initial-mode or initial-family stops contributing to the configuration; the live catalog and selection stay as they are, and the removal takes effect on the next mount (where resolveRuntimeOptions runs again). transition and scheduled are the exception: removing them turns the subsystem off, because "off" is expressible for them.

The element never writes its own observed attributes, so an attribute change always originates from the consumer and cannot feed back into itself. The configuring guard additionally covers a consumer that reflects state into the attribute during themes-change.

<themvora-provider themes="light dark plum-dark" default-theme="light">
  ...
</themvora-provider>

class ThemvoraRuntimeConsumer

Extends CustomElementBase Base class for a Themvora element that reads and follows the nearest <themvora-provider>'s runtime.

The lifecycle problem it solves

A descendant element can connect before, after, or instead of its provider initializing, and a provider that is removed and re-added creates a new runtime. Handling that by hand produced three defects that this base class removes:

1. A one-shot listener that never fires. The provider dispatches theme-ready on itself with bubbles: true, which travels up the tree and can never reach a descendant. Listening on the element itself only worked when the provider happened to initialize first.
2. Duplicate subscriptions. Every reconnection ran init() again and added another store listener, so a re-mounted element updated twice, three times, and so on.
3. Stale runtimes. After a provider was recreated, an element kept listening to the destroyed runtime and silently stopped updating.

Subclasses implement ThemvoraRuntimeConsumer.onRuntime to subscribe and ThemvoraRuntimeConsumer.onDetach to release what they took. Reconnection re-runs the pair, so a subscription can never outlive its connection or be created twice.

The catalog subscription is taken by this class, not by each subclass: every consumer that resolves themes itself (a scope, a family selector) must see a catalog change, and the runtime's registry notification is the one signal that reports it in the same task.

Subclasses that override connectedCallback / disconnectedCallback must call super.

class ThemvoraScope

Extends ThemvoraRuntimeConsumer Custom element <themvora-scope> that applies a scoped theme to its subtree.

Framework-free (vanilla JS). Applies the theme named by the theme attribute as CSS variables on the element, overriding the provider's selection for the subtree. Consumer markup stays in the light DOM, so the variables inherit into it normally. Observes the theme and theme-transition attributes.

See also: defineCustomElements, ThemvoraProvider