@theme-kit/nuxt

Functions

auto(tokenName, lookup): string

Returns string

buildThemeCssMap<T extends ThemeDefinition<string>>(themes, options?): Record<string, Record<string, string>>

Build a lookup map of theme keys to flat CSS variables.

Each theme is registered twice:

• under its own name (e.g. "sunrise-light")
• under a family:mode key (e.g. "sunrise:light") so that a persisted family + effective mode can be resolved without knowing theme names.

Returns Record<string, Record<string, string>>

calculateSunTimes(date, args...): { sunrise: Date; sunset: Date }

Compute today's sunrise and sunset using the standard NOAA solar algorithm (zenith-based, corrected for the equation of time).

latitude and longitude are optional: when omitted (or when an options object is passed instead), the location is resolved from timeZone or the visitor's browser timezone via resolveSolarLocation. Passing neither coordinates nor a timezone means every visitor gets sunrise/sunset for their own location automatically.

1// Explicit coordinates (unchanged behavior).
2calculateSunTimes(date, 48.8566, 2.3522);
3
4// Resolve from the visitor's timezone.
5calculateSunTimes(date);
6
7// Resolve from an explicit timezone.
8calculateSunTimes(date, { timeZone: "Asia/Kathmandu" });

Returns { sunrise: Date; sunset: Date }

cancelThemeAnimation(target): void

Abort any in-flight theme animation for target and remove its styles.

Returns void

clearMigrations(): void

Returns void

composeTheme<TName extends string>(name, sources...): ThemeDefinition<TName>

Returns ThemeDefinition<TName>

computeFingerprint(themes, defaultTheme?): string

Fingerprint the theme configuration so stale cookies from an older build (different themes / default) are ignored instead of being applied against themes they were never valid for.

Mirrors @theme-kit/next's computeFingerprint so both SSR integrations agree on the same cookie contract.

Returns string

contrast(background): string

Returns string

createAccessibilityPlugin<T extends ThemeDefinition<string>>(options?): ThemePlugin<T>

Returns ThemePlugin<T>

createAdapterRegistry<T extends ThemeDefinition<string>>(runtime): AdapterRegistry<T>

Returns AdapterRegistry<T>

createAnimationsPlugin<T extends ThemeDefinition<string>>(options?): ThemePlugin<T>

Returns ThemePlugin<T>

createBroadcastPlugin<T extends ThemeDefinition<string>>(options?): ThemePlugin<T>

Returns ThemePlugin<T>

createCSSVariablesBinding(store, options?): { destroy: void } | null

Returns { destroy: void } | null

createDebuggerPlugin<T extends ThemeDefinition<string>>(options?): ThemePlugin<T>

Returns ThemePlugin<T>

createDefaultPersistence(): ThemeSelectionPersistenceAdapter | null

Returns ThemeSelectionPersistenceAdapter | null

createDevToolsPlugin<T extends ThemeDefinition<string>>(options?): ThemePlugin<T>

Returns ThemePlugin<T>

createDOMBinding(store, options?): { apply: __type(theme: ThemeDefinition, emitOptions?: { suppressTransition?: boolean }): void; destroy: void } | null

Returns { apply: __type(theme: ThemeDefinition, emitOptions?: { suppressTransition?: boolean }): void; destroy: void } | null

createGenerationPlugin<T extends ThemeDefinition<string>>(options?): ThemePlugin<T>

Returns ThemePlugin<T>

createHistoryPlugin<T extends ThemeDefinition<string>>(options?): ThemePlugin<T>

Returns ThemePlugin<T>

createMultiWindowSync(options?): ThemeSelectionBroadcastAdapter

Returns ThemeSelectionBroadcastAdapter

createNoopSync(): ThemeSelectionBroadcastAdapter

Returns ThemeSelectionBroadcastAdapter

createNuxtThemeBootstrapScript<T extends ThemeDefinition<string>>(options): string

Generate the blocking, inline bootstrap script that applies the persisted theme before first paint — the same zero-flash guarantee @theme-kit/next ships.

The script reads the four theme cookies (same contract as Next), validates the config fingerprint, resolves the theme for the effective mode ("system" is resolved against prefers-color-scheme), and writes the CSS variables plus DOM effects onto document.documentElement. All theme knowledge (CSS maps, default resolution) comes from @theme-kit/core — this file is only glue wiring the cookie contract into the rendered HTML.

Emit it in <head> with tagPriority: "critical" so it runs before the app stylesheets and the browser paints already themed.

Returns string

createOverlayScrollbar(store, options?): OverlayScrollbarHandle | null

Framework-agnostic, theme-aware scrollbar overlay engine.

The browser performs all scrolling — this only renders + animates a visual overlay that tracks it, so inertia, touch, wheel, keyboard and accessibility remain native. Colors come from Theme Kit tokens, so the overlay re-themes with the rest of the app (no flashes). It tracks the document plus every scrollable element on the page by default (anywhere a native scrollbar would appear); the native track is hidden automatically — no manual CSS required.

Returns OverlayScrollbarHandle | null

createPersistencePlugin<T extends ThemeDefinition<string>>(options?): ThemePlugin<T>

Returns ThemePlugin<T>

createPluginManager<T extends ThemeDefinition<string>>(): PluginManager<T>

Returns PluginManager<T>

createPrePaintScrollbarCSS(): string

The hiding CSS, for SSR output (e.g. Next inlines it as a <style> in <head>). Use together with the tk-scrollbar class on <html>.

Returns string

createPrePaintScrollbarScript(options?): string

Generate a blocking <script> that hides the native scrollbar before first paint. The script is idempotent — calling it multiple times is safe. On coarse-pointer devices it returns early (unless touch is forced), so native scrollbars are kept.

Returns string

createScheduledPlugin<T extends ThemeDefinition<string>>(options): ThemePlugin<T>

Returns ThemePlugin<T>

createScheduledThemeBinding<T>(store, options): { destroy: void; getEnabled: void; getLocation: void; setEnabled: void; setLastSyncTime: void }

Returns { destroy: void; getEnabled: void; getLocation: void; setEnabled: void; setLastSyncTime: void }

createScopedThemeBinding<T extends ThemeDefinition<string>>(themes, target, selection, options?): { destroy: void; getTheme: void; setLocalThemes: void; setTransition: void; update: void }

Returns { destroy: void; getTheme: void; setLocalThemes: void; setTransition: void; update: void }

createSharedWorkerSync(): ThemeSelectionBroadcastAdapter | null

Returns ThemeSelectionBroadcastAdapter | null

createStorageEventSync(key?, view?): ThemeSelectionBroadcastAdapter

Returns ThemeSelectionBroadcastAdapter

createSystemThemeBinding<T extends ThemeDefinition<string>>(store, options): { destroy: void } | null

Returns { destroy: void } | null

createThemeBootstrapScript<T extends ThemeDefinition<string>>(options): string

Generate an inline, blocking script that applies the persisted theme before first paint, preventing a flash of the wrong (or missing) theme on reload.

The script reads the saved selection from localStorage, resolves the theme for the effective mode ("system" is resolved against prefers-color-scheme), and writes the CSS variables plus DOM effects onto document.documentElement.

Returns string

createThemeBroadcast(options?): ThemeBroadcastAdapter | null

Returns ThemeBroadcastAdapter | null

createThemeDebugger<T extends ThemeDefinition<string>>(store, options?): ThemeDebugger<T>

Returns ThemeDebugger<T>

createThemeDiff(prev, next, prefix?): ThemeDiff

Theme Diff Engine.

Compares the previously applied CSS variables against the incoming theme's variables per token group. Comparing the final resolved values (rather than raw theme definitions) means two themes that resolve to identical colors produce no diff — and nothing animates.

Returns ThemeDiff

createThemeHistory<T extends ThemeDefinition<string>>(store, options?): ThemeHistory<T>

Returns ThemeHistory<T>

createThemeLifecycle<T extends ThemeDefinition<string>>(): ThemeLifecycle<T>

Returns ThemeLifecycle<T>

createThemeModeController<T extends ThemeDefinition<string>>(options): { setMode: __type(nextMode: ThemeMode): void; destroy: void; getMode: void }

Returns { setMode: __type(nextMode: ThemeMode): void; destroy: void; getMode: void }

createThemePersistence(options?): ThemePersistenceAdapter | null

Returns ThemePersistenceAdapter | null

createThemeRegistry<T extends ThemeDefinition<string>>(options?): ThemeRegistry<T>

Returns ThemeRegistry<T>

createThemeRuntime<T extends ThemeDefinition<string>>(options): ThemeRuntime<T>

Returns ThemeRuntime<T>

createThemeSchedule<T extends ThemeDefinition<string>>(store, themes, options): ThemeSchedule

Framework-neutral sunrise/sunset scheduling controller. Wraps the core createScheduledThemeBinding engine with an explicit on/off switch and a reactive state snapshot (sunrise, sunset, nextTransition, ...) so frameworks can expose it through their native accessors.

lightTheme and darkTheme are optional: when omitted the schedule derives them from the currently selected theme's family (e.g. current plum-dark → scheduled plum-light/plum-dark) and falls back to the built-in neutral light/dark themes, re-resolving whenever the user switches theme family.

The engine itself lives entirely in core — every framework wrapper talks to this single contract.

Returns ThemeSchedule

createThemeScrollbar(store, options?): OverlayScrollbarHandle | null

Alias landing in the public API.

Returns OverlayScrollbarHandle | null

createThemeSelectionBroadcast(options?): ThemeSelectionBroadcastAdapter | null

Returns ThemeSelectionBroadcastAdapter | null

createThemeStore<T extends ThemeDefinition<string>>(options): ThemeStore<T>

Returns ThemeStore<T>

createTransitionPlan(diff, options?, env?): TransitionPlan | null

Transition Planner.

Turns a ThemeDiff into a concrete TransitionPlan:

• colors animate through the registered theme custom properties on :root,
• every other changed group contributes the concrete CSS properties it maps to (radius → border-radius, spacing → padding/margin/gap, …).

Returns null when there is nothing animatable: transitions disabled, reduced motion, an "instant" preset, or a diff where only non-animatable groups (layout/z-index/breakpoints) changed.

Returns TransitionPlan | null

darkModeCSSTemplate(variables): string

Generate a @media (prefers-color-scheme: dark) CSS block carrying the given variables. Useful when the initial mode is "system" and the light theme is rendered statically, so dark-mode users get the correct colors without JS.

Returns string

defineTheme<Name extends string, T extends ThemeDefinition<Name>>(theme): T

Returns T

destroySharedWorkerUrl(): void

Returns void

evaluateExpression(expr): string

Returns string

extendTheme<TName extends string, TBase extends ThemeDefinition<string>>(name, base, overrides?): ThemeDefinition<TName>

Returns ThemeDefinition<TName>

flattenTokens(tokens): Record<string, string>

Returns Record<string, string>

generateTheme(options): GeneratedThemePair

Returns GeneratedThemePair

getAccessibilityProfiles(): { meta: { label: string; mode: "light" | "dark"; order: number; tags: string[] }; name: "high-contrast-light" | "high-contrast-dark"; tokens: { colors: { accent: string; accentForeground: string; background: string; border: string; card: string; cardForeground: string; destructive: string; destructiveForeground: string; foreground: string; input: string; muted: string; mutedForeground: string; popover: string; popoverForeground: string; primary: string; primaryForeground: string; ring: string; secondary: string; secondaryForeground: string; success: string; successForeground: string }; radius: { lg: string } } } | { meta: { label: string; mode: "light" | "dark"; order: number; tags: string[] }; name: "large-text-light" | "large-text-dark"; tokens: { colors: { accent: string; accentForeground: string; background: string; border: string; card: string; cardForeground: string; destructive: string; destructiveForeground: string; foreground: string; input: string; muted: string; mutedForeground: string; popover: string; popoverForeground: string; primary: string; primaryForeground: string; ring: string; secondary: string; secondaryForeground: string; success: string; successForeground: string }; radius: { lg: string }; typography: { fontFamilies: { mono: string; sans: string }; fontSizes: { 2xl: string; 3xl: string; 4xl: string; 5xl: string; 6xl: string; base: string; lg: string; sm: string; xl: string; xs: string }; lineHeights: { normal: string; relaxed: string; tight: string } } } }[]

Returns { meta: { label: string; mode: "light" | "dark"; order: number; tags: string[] }; name: "high-contrast-light" | "high-contrast-dark"; tokens: { colors: { accent: string; accentForeground: string; background: string; border: string; card: string; cardForeground: string; destructive: string; destructiveForeground: string; foreground: string; input: string; muted: string; mutedForeground: string; popover: string; popoverForeground: string; primary: string; primaryForeground: string; ring: string; secondary: string; secondaryForeground: string; success: string; successForeground: string }; radius: { lg: string } } } | { meta: { label: string; mode: "light" | "dark"; order: number; tags: string[] }; name: "large-text-light" | "large-text-dark"; tokens: { colors: { accent: string; accentForeground: string; background: string; border: string; card: string; cardForeground: string; destructive: string; destructiveForeground: string; foreground: string; input: string; muted: string; mutedForeground: string; popover: string; popoverForeground: string; primary: string; primaryForeground: string; ring: string; secondary: string; secondaryForeground: string; success: string; successForeground: string }; radius: { lg: string }; typography: { fontFamilies: { mono: string; sans: string }; fontSizes: { 2xl: string; 3xl: string; 4xl: string; 5xl: string; 6xl: string; base: string; lg: string; sm: string; xl: string; xs: string }; lineHeights: { normal: string; relaxed: string; tight: string } } } }[]

getBrandPresets(): { meta: { family: string; label: string; mode: "light" | "dark"; order: number }; name: ${unknown}|${unknown}; tokens: { colors: { accent: string; accentForeground: string; background: string; border: string; card: string; cardForeground: string; destructive: string; destructiveForeground: string; foreground: string; input: string; muted: string; mutedForeground: string; popover: string; popoverForeground: string; primary: string; primaryForeground: string; ring: string; secondary: string; secondaryForeground: string; success: string; successForeground: string }; radius: { lg: string } } }[]

Returns { meta: { family: string; label: string; mode: "light" | "dark"; order: number }; name: ${unknown}|${unknown}; tokens: { colors: { accent: string; accentForeground: string; background: string; border: string; card: string; cardForeground: string; destructive: string; destructiveForeground: string; foreground: string; input: string; muted: string; mutedForeground: string; popover: string; popoverForeground: string; primary: string; primaryForeground: string; ring: string; secondary: string; secondaryForeground: string; success: string; successForeground: string }; radius: { lg: string } } }[]

getBrowserTimeZone(): string | null

Detect the visitor's IANA timezone, e.g. "Asia/Kathmandu". Returns null when Intl is unavailable or reports an empty zone.

Returns string | null

getBuiltInThemes(): { meta: { label: string; mode: "light" | "dark"; order: number; tags: string[] }; name: "high-contrast-light" | "high-contrast-dark"; tokens: { colors: { accent: string; accentForeground: string; background: string; border: string; card: string; cardForeground: string; destructive: string; destructiveForeground: string; foreground: string; input: string; muted: string; mutedForeground: string; popover: string; popoverForeground: string; primary: string; primaryForeground: string; ring: string; secondary: string; secondaryForeground: string; success: string; successForeground: string }; radius: { lg: string } } } | { meta: { label: string; mode: "light" | "dark"; order: number; tags: string[] }; name: "large-text-light" | "large-text-dark"; tokens: { colors: { accent: string; accentForeground: string; background: string; border: string; card: string; cardForeground: string; destructive: string; destructiveForeground: string; foreground: string; input: string; muted: string; mutedForeground: string; popover: string; popoverForeground: string; primary: string; primaryForeground: string; ring: string; secondary: string; secondaryForeground: string; success: string; successForeground: string }; radius: { lg: string }; typography: { fontFamilies: { mono: string; sans: string }; fontSizes: { 2xl: string; 3xl: string; 4xl: string; 5xl: string; 6xl: string; base: string; lg: string; sm: string; xl: string; xs: string }; lineHeights: { normal: string; relaxed: string; tight: string } } } } | { meta: { family: string; label: string; mode: "light" | "dark"; order: number }; name: ${unknown}|${unknown}; tokens: { colors: { accent: string; accentForeground: string; background: string; border: string; card: string; cardForeground: string; destructive: string; destructiveForeground: string; foreground: string; input: string; muted: string; mutedForeground: string; popover: string; popoverForeground: string; primary: string; primaryForeground: string; ring: string; secondary: string; secondaryForeground: string; success: string; successForeground: string }; radius: { lg: string } } } | { meta: { label: string; mode: "light"; order: number }; name: "light"; tokens: { borderWidths: { 0: string; 1: string; 2: string; 4: string; 8: string }; breakpoints: { 2xl: string; lg: string; md: string; sm: string; xl: string }; code: { attribute: string; background: string; border: string; comment: string; foreground: string; function: string; gutter: string; highlight: string; keyword: string; lineNumber: string; number: string; operator: string; property: string; punctuation: string; selection: string; string: string; tag: string; type: string; variable: string }; colors: { accent: string; accentForeground: string; background: string; border: string; card: string; cardForeground: string; destructive: string; destructiveForeground: string; foreground: string; input: string; muted: string; mutedForeground: string; popover: string; popoverForeground: string; primary: string; primaryForeground: string; ring: string; secondary: string; secondaryForeground: string; success: string; successForeground: string }; radius: { 2xl: string; full: string; lg: string; md: string; sm: string; xl: string }; shadows: { 2xl: string; lg: string; md: string; sm: string; xl: string; xs: string }; spacing: { 0: string; 0.5: string; 1: string; 1.5: string; 10: string; 11: string; 12: string; 14: string; 16: string; 2: string; 2.5: string; 20: string; 24: string; 3: string; 3.5: string; 4: string; 5: string; 6: string; 7: string; 8: string; 9: string; px: string }; typography: { fontFamilies: { mono: string; sans: string; serif: string }; fontSizes: { 2xl: string; 3xl: string; 4xl: string; 5xl: string; base: string; lg: string; sm: string; xl: string; xs: string }; lineHeights: { loose: string; none: string; normal: string; relaxed: string; snug: string; tight: string } }; zIndex: { 0: string; 10: string; 20: string; 30: string; 40: string; 50: string; auto: string } } } | { meta: { label: string; mode: "dark"; order: number }; name: "dark"; tokens: { borderWidths: { 0: string; 1: string; 2: string; 4: string; 8: string }; breakpoints: { 2xl: string; lg: string; md: string; sm: string; xl: string }; code: { attribute: string; background: string; border: string; comment: string; foreground: string; function: string; gutter: string; highlight: string; keyword: string; lineNumber: string; number: string; operator: string; property: string; punctuation: string; selection: string; string: string; tag: string; type: string; variable: string }; colors: { accent: string; accentForeground: string; background: string; border: string; card: string; cardForeground: string; destructive: string; destructiveForeground: string; foreground: string; input: string; muted: string; mutedForeground: string; popover: string; popoverForeground: string; primary: string; primaryForeground: string; ring: string; secondary: string; secondaryForeground: string; success: string; successForeground: string }; radius: { 2xl: string; full: string; lg: string; md: string; sm: string; xl: string }; shadows: { 2xl: string; lg: string; md: string; sm: string; xl: string; xs: string }; spacing: { 0: string; 0.5: string; 1: string; 1.5: string; 10: string; 11: string; 12: string; 14: string; 16: string; 2: string; 2.5: string; 20: string; 24: string; 3: string; 3.5: string; 4: string; 5: string; 6: string; 7: string; 8: string; 9: string; px: string }; typography: { fontFamilies: { mono: string; sans: string; serif: string }; fontSizes: { 2xl: string; 3xl: string; 4xl: string; 5xl: string; base: string; lg: string; sm: string; xl: string; xs: string }; lineHeights: { loose: string; none: string; normal: string; relaxed: string; snug: string; tight: string } }; zIndex: { 0: string; 10: string; 20: string; 30: string; 40: string; 50: string; auto: string } } } | { meta: { family: "oat" | "berry" | "mint" | "citrus" | "cocoa" | "plum" | "iris" | "sky" | "graphite"; label: string; mode: "light" | "dark"; order: number }; name: "oat-light" | "oat-dark" | "berry-light" | "berry-dark" | "mint-light" | "mint-dark" | "citrus-light" | "citrus-dark" | "cocoa-light" | "cocoa-dark" | "plum-light" | "plum-dark" | "iris-light" | "iris-dark" | "sky-light" | "sky-dark" | "graphite-light" | "graphite-dark"; tokens: ThemeTokens }[]

Returns { meta: { label: string; mode: "light" | "dark"; order: number; tags: string[] }; name: "high-contrast-light" | "high-contrast-dark"; tokens: { colors: { accent: string; accentForeground: string; background: string; border: string; card: string; cardForeground: string; destructive: string; destructiveForeground: string; foreground: string; input: string; muted: string; mutedForeground: string; popover: string; popoverForeground: string; primary: string; primaryForeground: string; ring: string; secondary: string; secondaryForeground: string; success: string; successForeground: string }; radius: { lg: string } } } | { meta: { label: string; mode: "light" | "dark"; order: number; tags: string[] }; name: "large-text-light" | "large-text-dark"; tokens: { colors: { accent: string; accentForeground: string; background: string; border: string; card: string; cardForeground: string; destructive: string; destructiveForeground: string; foreground: string; input: string; muted: string; mutedForeground: string; popover: string; popoverForeground: string; primary: string; primaryForeground: string; ring: string; secondary: string; secondaryForeground: string; success: string; successForeground: string }; radius: { lg: string }; typography: { fontFamilies: { mono: string; sans: string }; fontSizes: { 2xl: string; 3xl: string; 4xl: string; 5xl: string; 6xl: string; base: string; lg: string; sm: string; xl: string; xs: string }; lineHeights: { normal: string; relaxed: string; tight: string } } } } | { meta: { family: string; label: string; mode: "light" | "dark"; order: number }; name: ${unknown}|${unknown}; tokens: { colors: { accent: string; accentForeground: string; background: string; border: string; card: string; cardForeground: string; destructive: string; destructiveForeground: string; foreground: string; input: string; muted: string; mutedForeground: string; popover: string; popoverForeground: string; primary: string; primaryForeground: string; ring: string; secondary: string; secondaryForeground: string; success: string; successForeground: string }; radius: { lg: string } } } | { meta: { label: string; mode: "light"; order: number }; name: "light"; tokens: { borderWidths: { 0: string; 1: string; 2: string; 4: string; 8: string }; breakpoints: { 2xl: string; lg: string; md: string; sm: string; xl: string }; code: { attribute: string; background: string; border: string; comment: string; foreground: string; function: string; gutter: string; highlight: string; keyword: string; lineNumber: string; number: string; operator: string; property: string; punctuation: string; selection: string; string: string; tag: string; type: string; variable: string }; colors: { accent: string; accentForeground: string; background: string; border: string; card: string; cardForeground: string; destructive: string; destructiveForeground: string; foreground: string; input: string; muted: string; mutedForeground: string; popover: string; popoverForeground: string; primary: string; primaryForeground: string; ring: string; secondary: string; secondaryForeground: string; success: string; successForeground: string }; radius: { 2xl: string; full: string; lg: string; md: string; sm: string; xl: string }; shadows: { 2xl: string; lg: string; md: string; sm: string; xl: string; xs: string }; spacing: { 0: string; 0.5: string; 1: string; 1.5: string; 10: string; 11: string; 12: string; 14: string; 16: string; 2: string; 2.5: string; 20: string; 24: string; 3: string; 3.5: string; 4: string; 5: string; 6: string; 7: string; 8: string; 9: string; px: string }; typography: { fontFamilies: { mono: string; sans: string; serif: string }; fontSizes: { 2xl: string; 3xl: string; 4xl: string; 5xl: string; base: string; lg: string; sm: string; xl: string; xs: string }; lineHeights: { loose: string; none: string; normal: string; relaxed: string; snug: string; tight: string } }; zIndex: { 0: string; 10: string; 20: string; 30: string; 40: string; 50: string; auto: string } } } | { meta: { label: string; mode: "dark"; order: number }; name: "dark"; tokens: { borderWidths: { 0: string; 1: string; 2: string; 4: string; 8: string }; breakpoints: { 2xl: string; lg: string; md: string; sm: string; xl: string }; code: { attribute: string; background: string; border: string; comment: string; foreground: string; function: string; gutter: string; highlight: string; keyword: string; lineNumber: string; number: string; operator: string; property: string; punctuation: string; selection: string; string: string; tag: string; type: string; variable: string }; colors: { accent: string; accentForeground: string; background: string; border: string; card: string; cardForeground: string; destructive: string; destructiveForeground: string; foreground: string; input: string; muted: string; mutedForeground: string; popover: string; popoverForeground: string; primary: string; primaryForeground: string; ring: string; secondary: string; secondaryForeground: string; success: string; successForeground: string }; radius: { 2xl: string; full: string; lg: string; md: string; sm: string; xl: string }; shadows: { 2xl: string; lg: string; md: string; sm: string; xl: string; xs: string }; spacing: { 0: string; 0.5: string; 1: string; 1.5: string; 10: string; 11: string; 12: string; 14: string; 16: string; 2: string; 2.5: string; 20: string; 24: string; 3: string; 3.5: string; 4: string; 5: string; 6: string; 7: string; 8: string; 9: string; px: string }; typography: { fontFamilies: { mono: string; sans: string; serif: string }; fontSizes: { 2xl: string; 3xl: string; 4xl: string; 5xl: string; base: string; lg: string; sm: string; xl: string; xs: string }; lineHeights: { loose: string; none: string; normal: string; relaxed: string; snug: string; tight: string } }; zIndex: { 0: string; 10: string; 20: string; 30: string; 40: string; 50: string; auto: string } } } | { meta: { family: "oat" | "berry" | "mint" | "citrus" | "cocoa" | "plum" | "iris" | "sky" | "graphite"; label: string; mode: "light" | "dark"; order: number }; name: "oat-light" | "oat-dark" | "berry-light" | "berry-dark" | "mint-light" | "mint-dark" | "citrus-light" | "citrus-dark" | "cocoa-light" | "cocoa-dark" | "plum-light" | "plum-dark" | "iris-light" | "iris-dark" | "sky-light" | "sky-dark" | "graphite-light" | "graphite-dark"; tokens: ThemeTokens }[]

getContrastRatio(foreground, background): number

Returns number

getDefaultThemes(): { meta: { family: string; label: string; mode: "light" | "dark"; order: number }; name: ${unknown}|${unknown}; tokens: { colors: { accent: string; accentForeground: string; background: string; border: string; card: string; cardForeground: string; destructive: string; destructiveForeground: string; foreground: string; input: string; muted: string; mutedForeground: string; popover: string; popoverForeground: string; primary: string; primaryForeground: string; ring: string; secondary: string; secondaryForeground: string }; radius: { lg: string } } }[]

Returns { meta: { family: string; label: string; mode: "light" | "dark"; order: number }; name: ${unknown}|${unknown}; tokens: { colors: { accent: string; accentForeground: string; background: string; border: string; card: string; cardForeground: string; destructive: string; destructiveForeground: string; foreground: string; input: string; muted: string; mutedForeground: string; popover: string; popoverForeground: string; primary: string; primaryForeground: string; ring: string; secondary: string; secondaryForeground: string }; radius: { lg: string } } }[]

getHighContrastTheme(mode): { meta: { label: string; mode: "light" | "dark"; order: number; tags: string[] }; name: "high-contrast-light" | "high-contrast-dark"; tokens: { colors: { accent: string; accentForeground: string; background: string; border: string; card: string; cardForeground: string; destructive: string; destructiveForeground: string; foreground: string; input: string; muted: string; mutedForeground: string; popover: string; popoverForeground: string; primary: string; primaryForeground: string; ring: string; secondary: string; secondaryForeground: string; success: string; successForeground: string }; radius: { lg: string } } }

Returns { meta: { label: string; mode: "light" | "dark"; order: number; tags: string[] }; name: "high-contrast-light" | "high-contrast-dark"; tokens: { colors: { accent: string; accentForeground: string; background: string; border: string; card: string; cardForeground: string; destructive: string; destructiveForeground: string; foreground: string; input: string; muted: string; mutedForeground: string; popover: string; popoverForeground: string; primary: string; primaryForeground: string; ring: string; secondary: string; secondaryForeground: string; success: string; successForeground: string }; radius: { lg: string } } }

getLargeTextTheme(mode): { meta: { label: string; mode: "light" | "dark"; order: number; tags: string[] }; name: "large-text-light" | "large-text-dark"; tokens: { colors: { accent: string; accentForeground: string; background: string; border: string; card: string; cardForeground: string; destructive: string; destructiveForeground: string; foreground: string; input: string; muted: string; mutedForeground: string; popover: string; popoverForeground: string; primary: string; primaryForeground: string; ring: string; secondary: string; secondaryForeground: string; success: string; successForeground: string }; radius: { lg: string }; typography: { fontFamilies: { mono: string; sans: string }; fontSizes: { 2xl: string; 3xl: string; 4xl: string; 5xl: string; 6xl: string; base: string; lg: string; sm: string; xl: string; xs: string }; lineHeights: { normal: string; relaxed: string; tight: string } } } }

Returns { meta: { label: string; mode: "light" | "dark"; order: number; tags: string[] }; name: "large-text-light" | "large-text-dark"; tokens: { colors: { accent: string; accentForeground: string; background: string; border: string; card: string; cardForeground: string; destructive: string; destructiveForeground: string; foreground: string; input: string; muted: string; mutedForeground: string; popover: string; popoverForeground: string; primary: string; primaryForeground: string; ring: string; secondary: string; secondaryForeground: string; success: string; successForeground: string }; radius: { lg: string }; typography: { fontFamilies: { mono: string; sans: string }; fontSizes: { 2xl: string; 3xl: string; 4xl: string; 5xl: string; 6xl: string; base: string; lg: string; sm: string; xl: string; xs: string }; lineHeights: { normal: string; relaxed: string; tight: string } } } }

getLocationForTimeZone(timeZone): TimeZoneLocation | null

Look up the reference coordinates for an IANA timezone. Returns null when the zone is unknown (or Etc/GMT±n, which is derived from offset).

Returns TimeZoneLocation | null

getNeutralThemes(): readonly [{ meta: { label: string; mode: "light"; order: number }; name: "light"; tokens: { borderWidths: { 0: string; 1: string; 2: string; 4: string; 8: string }; breakpoints: { 2xl: string; lg: string; md: string; sm: string; xl: string }; code: { attribute: string; background: string; border: string; comment: string; foreground: string; function: string; gutter: string; highlight: string; keyword: string; lineNumber: string; number: string; operator: string; property: string; punctuation: string; selection: string; string: string; tag: string; type: string; variable: string }; colors: { accent: string; accentForeground: string; background: string; border: string; card: string; cardForeground: string; destructive: string; destructiveForeground: string; foreground: string; input: string; muted: string; mutedForeground: string; popover: string; popoverForeground: string; primary: string; primaryForeground: string; ring: string; secondary: string; secondaryForeground: string; success: string; successForeground: string }; radius: { 2xl: string; full: string; lg: string; md: string; sm: string; xl: string }; shadows: { 2xl: string; lg: string; md: string; sm: string; xl: string; xs: string }; spacing: { 0: string; 0.5: string; 1: string; 1.5: string; 10: string; 11: string; 12: string; 14: string; 16: string; 2: string; 2.5: string; 20: string; 24: string; 3: string; 3.5: string; 4: string; 5: string; 6: string; 7: string; 8: string; 9: string; px: string }; typography: { fontFamilies: { mono: string; sans: string; serif: string }; fontSizes: { 2xl: string; 3xl: string; 4xl: string; 5xl: string; base: string; lg: string; sm: string; xl: string; xs: string }; lineHeights: { loose: string; none: string; normal: string; relaxed: string; snug: string; tight: string } }; zIndex: { 0: string; 10: string; 20: string; 30: string; 40: string; 50: string; auto: string } } }, { meta: { label: string; mode: "dark"; order: number }; name: "dark"; tokens: { borderWidths: { 0: string; 1: string; 2: string; 4: string; 8: string }; breakpoints: { 2xl: string; lg: string; md: string; sm: string; xl: string }; code: { attribute: string; background: string; border: string; comment: string; foreground: string; function: string; gutter: string; highlight: string; keyword: string; lineNumber: string; number: string; operator: string; property: string; punctuation: string; selection: string; string: string; tag: string; type: string; variable: string }; colors: { accent: string; accentForeground: string; background: string; border: string; card: string; cardForeground: string; destructive: string; destructiveForeground: string; foreground: string; input: string; muted: string; mutedForeground: string; popover: string; popoverForeground: string; primary: string; primaryForeground: string; ring: string; secondary: string; secondaryForeground: string; success: string; successForeground: string }; radius: { 2xl: string; full: string; lg: string; md: string; sm: string; xl: string }; shadows: { 2xl: string; lg: string; md: string; sm: string; xl: string; xs: string }; spacing: { 0: string; 0.5: string; 1: string; 1.5: string; 10: string; 11: string; 12: string; 14: string; 16: string; 2: string; 2.5: string; 20: string; 24: string; 3: string; 3.5: string; 4: string; 5: string; 6: string; 7: string; 8: string; 9: string; px: string }; typography: { fontFamilies: { mono: string; sans: string; serif: string }; fontSizes: { 2xl: string; 3xl: string; 4xl: string; 5xl: string; base: string; lg: string; sm: string; xl: string; xs: string }; lineHeights: { loose: string; none: string; normal: string; relaxed: string; snug: string; tight: string } }; zIndex: { 0: string; 10: string; 20: string; 30: string; 40: string; 50: string; auto: string } } }]

Returns readonly [{ meta: { label: string; mode: "light"; order: number }; name: "light"; tokens: { borderWidths: { 0: string; 1: string; 2: string; 4: string; 8: string }; breakpoints: { 2xl: string; lg: string; md: string; sm: string; xl: string }; code: { attribute: string; background: string; border: string; comment: string; foreground: string; function: string; gutter: string; highlight: string; keyword: string; lineNumber: string; number: string; operator: string; property: string; punctuation: string; selection: string; string: string; tag: string; type: string; variable: string }; colors: { accent: string; accentForeground: string; background: string; border: string; card: string; cardForeground: string; destructive: string; destructiveForeground: string; foreground: string; input: string; muted: string; mutedForeground: string; popover: string; popoverForeground: string; primary: string; primaryForeground: string; ring: string; secondary: string; secondaryForeground: string; success: string; successForeground: string }; radius: { 2xl: string; full: string; lg: string; md: string; sm: string; xl: string }; shadows: { 2xl: string; lg: string; md: string; sm: string; xl: string; xs: string }; spacing: { 0: string; 0.5: string; 1: string; 1.5: string; 10: string; 11: string; 12: string; 14: string; 16: string; 2: string; 2.5: string; 20: string; 24: string; 3: string; 3.5: string; 4: string; 5: string; 6: string; 7: string; 8: string; 9: string; px: string }; typography: { fontFamilies: { mono: string; sans: string; serif: string }; fontSizes: { 2xl: string; 3xl: string; 4xl: string; 5xl: string; base: string; lg: string; sm: string; xl: string; xs: string }; lineHeights: { loose: string; none: string; normal: string; relaxed: string; snug: string; tight: string } }; zIndex: { 0: string; 10: string; 20: string; 30: string; 40: string; 50: string; auto: string } } }, { meta: { label: string; mode: "dark"; order: number }; name: "dark"; tokens: { borderWidths: { 0: string; 1: string; 2: string; 4: string; 8: string }; breakpoints: { 2xl: string; lg: string; md: string; sm: string; xl: string }; code: { attribute: string; background: string; border: string; comment: string; foreground: string; function: string; gutter: string; highlight: string; keyword: string; lineNumber: string; number: string; operator: string; property: string; punctuation: string; selection: string; string: string; tag: string; type: string; variable: string }; colors: { accent: string; accentForeground: string; background: string; border: string; card: string; cardForeground: string; destructive: string; destructiveForeground: string; foreground: string; input: string; muted: string; mutedForeground: string; popover: string; popoverForeground: string; primary: string; primaryForeground: string; ring: string; secondary: string; secondaryForeground: string; success: string; successForeground: string }; radius: { 2xl: string; full: string; lg: string; md: string; sm: string; xl: string }; shadows: { 2xl: string; lg: string; md: string; sm: string; xl: string; xs: string }; spacing: { 0: string; 0.5: string; 1: string; 1.5: string; 10: string; 11: string; 12: string; 14: string; 16: string; 2: string; 2.5: string; 20: string; 24: string; 3: string; 3.5: string; 4: string; 5: string; 6: string; 7: string; 8: string; 9: string; px: string }; typography: { fontFamilies: { mono: string; sans: string; serif: string }; fontSizes: { 2xl: string; 3xl: string; 4xl: string; 5xl: string; base: string; lg: string; sm: string; xl: string; xs: string }; lineHeights: { loose: string; none: string; normal: string; relaxed: string; snug: string; tight: string } }; zIndex: { 0: string; 10: string; 20: string; 30: string; 40: string; 50: string; auto: string } } }]

getPresetThemes(overrides?): { meta: { family: "oat" | "berry" | "mint" | "citrus" | "cocoa" | "plum" | "iris" | "sky" | "graphite"; label: string; mode: "light" | "dark"; order: number }; name: "oat-light" | "oat-dark" | "berry-light" | "berry-dark" | "mint-light" | "mint-dark" | "citrus-light" | "citrus-dark" | "cocoa-light" | "cocoa-dark" | "plum-light" | "plum-dark" | "iris-light" | "iris-dark" | "sky-light" | "sky-dark" | "graphite-light" | "graphite-dark"; tokens: ThemeTokens }[]

Returns { meta: { family: "oat" | "berry" | "mint" | "citrus" | "cocoa" | "plum" | "iris" | "sky" | "graphite"; label: string; mode: "light" | "dark"; order: number }; name: "oat-light" | "oat-dark" | "berry-light" | "berry-dark" | "mint-light" | "mint-dark" | "citrus-light" | "citrus-dark" | "cocoa-light" | "cocoa-dark" | "plum-light" | "plum-dark" | "iris-light" | "iris-dark" | "sky-light" | "sky-dark" | "graphite-light" | "graphite-dark"; tokens: ThemeTokens }[]

getThemeFamily(theme): string

Returns string

getThemeMode(theme): ThemeMode

The color mode of a theme. Uses meta.mode when present; otherwise infers it from the theme name (e.g. "mint-dark" → "dark"). This keeps simple theme definitions working: [{ name: "light", ... }, { name: "dark", ... }] resolve and toggle correctly without requiring meta.mode.

Returns ThemeMode

getTimeZoneList(): string[]

All known timezone ids, sorted alphabetically. Useful for building pickers (the docs site uses it for its timezone selector).

Returns string[]

isExpression(value): boolean

Returns boolean

isSettled(current, target, epsilon?): boolean

True when two positions are close enough to consider the thumb "settled".

Returns boolean

mergePresetTokens(base, override?): ThemeTokens

Returns ThemeTokens

mergeThemeDefinitions<Name extends string>(base, override): ThemeDefinition<Name>

Returns ThemeDefinition<Name>

mergeTokens(base, override): ThemeTokens | undefined

Returns ThemeTokens | undefined

migrateTheme(theme, options?): ThemeDefinition

Returns ThemeDefinition

parseCookieHeader(header): ParsedCookies

Minimal RFC 6265 header parser — enough for the four theme cookies.

Returns ParsedCookies

prefersReducedMotion(): boolean

Requested motion profile. Reduced motion snaps instantly.

Returns boolean

registerMigration(step): void

Returns void

resolveInitialTheme<T extends ThemeDefinition<string>>(options): InitialThemeResolution<T>

Returns InitialThemeResolution<T>

resolveScheduledThemePair<T extends ThemeDefinition<string>>(themes, options, current?): { dark: T | null; light: T | null }

Resolve the scheduled light/dark themes from the configured options and the currently selected theme. Priority: explicit lightTheme/darkTheme → same-family counterpart of the current theme → neutral light/dark. Shared by createThemeSchedule and createScheduledPlugin.

Returns { dark: T | null; light: T | null }

resolveScopedTheme<T extends ThemeDefinition<string>>(themes, selection, prefersDark?): T

Resolve a scoped selection against a theme list. themes should already be the combined source: local themes FIRST, then the parent runtime's registry.

Resolution order:

1. exact theme-name match (local wins),
2. a name that matches a family → that family's theme for the mode,
3. explicit family + mode → exact match, else the family's light theme, else the family's first theme,
4. the first theme in the list as a last-resort fallback.

The resolved definition has its extends chain merged (like resolveTheme) so scoped CSS variables include every inherited token.

Returns T

resolveScopedThemePrePaint<T extends ThemeDefinition<string>>(themes, selection, options?): ScopedThemePrePaint

Resolve everything a scope needs for its FIRST PAINT, generically from its theme data (no hardcoded colors — any user's scoped themes produce the same result). When the selection is OS-dependent (a system mode, or a family / boundary scope currently following a system selection), it returns a @media (prefers-color-scheme: dark) CSS block so the scoped region renders light OR dark correctly before hydration, with the live binding taking over through its own inline variables afterwards.

Returns ScopedThemePrePaint

resolveScopeTransition(parent, local): ThemeTransitionOptions | undefined

Merge a scope's transition over its parent runtime's transition.

The inheritance model is ThemeProvider transition → ThemeScope → inherited defaults → local overrides:

• local === undefined → inherit the parent's configuration unchanged,
• local === true → inherit the parent's configuration unchanged,
• local === false → transitions disabled for this scope only,
• local object → merged over the parent's (local keys win).

Frameworks use this so <ThemeScope transition={{ duration: 200 }}> flips just the duration without the user having to repeat the provider's easing / preset.

Returns ThemeTransitionOptions | undefined

resolveSelectedTheme<T extends ThemeDefinition<string>>(themes, selection): T

Returns T

resolveSelection<T extends ThemeDefinition<string>>(options): ThemeSelectionState

Returns ThemeSelectionState

resolveSelectionTheme<T extends ThemeDefinition<string>>(options): SelectionThemeResolution<T>

Returns SelectionThemeResolution<T>

resolveSolarLocation(input?): ResolvedSolarLocation

Resolve the coordinates a solar calculation should use.

Priority: explicit latitude/longitude → explicit timeZone → browser timezone auto-detection → DEFAULT_TIMEZONE_LOCATION.

Returns ResolvedSolarLocation

resolveTheme<Name extends string>(themes, themeName, resolveTokenRefs?): ThemeDefinition<Name>

Returns ThemeDefinition<Name>

resolveThemeFromCookies<T extends ThemeDefinition<string>>(options): InitialThemeResolution<T>

SSR-first theme resolution. Reads the four theme cookies from the request, rejects them when the config fingerprint is stale, and resolves the initial theme for the effective selection — exactly like @theme-kit/next's getInitialThemeState.

The resolved <html> state (theme name, family, mode) can then be rendered server-side so the browser paints already themed.

Returns InitialThemeResolution<T>

resolveThemeName<Name extends string>(themes, family, mode, prefersDark?): Name

Returns Name

resolveThemeRegistry<T extends ThemeDefinition<string>>(options?): readonly T[]

Returns readonly T[]

resolveTokens(tokens): ThemeTokens

Returns ThemeTokens

runThemeAnimation(input): void

Run the animation for one theme change. Called by the CSS-variables binding only when the Transition Planner produced a non-null plan.

Returns void

scanForTransition(root, properties): HTMLElement[]

Collect elements that both (a) are visible and (b) actually use one of the provided CSS properties. Runs only when non-color groups are animating.

Returns HTMLElement[]

scopeToCSSVariables(themeVars, prefix?): Record<string, string>

Mirror the scoped binding's aliases (the --color-* / --radius-* tokens Tailwind-style utilities resolve against) so styling utilities on scoped elements use the scoped theme's values, not the page theme's.

Returns Record<string, string>

simulateCVD(hex, type): string

Returns string

simulateThemeForCVD(theme, type): ThemeDefinition

Returns ThemeDefinition

themeToCSSVariables(theme, options?): Record<string, string>

Returns Record<string, string>

useBootstrapTheme<T extends ThemeDefinition<string>>(options?): ThemeAdapter<T>

Vue composable that installs the Bootstrap adapter onto the active Theme Kit runtime. Maintains a tagged :root style element with concrete --bs-* variables (including -rgb triplets), kept in sync as the active theme changes.

Returns ThemeAdapter<T>

useDaisyTheme<T extends ThemeDefinition<string>>(options?): ThemeAdapter<T>

Vue composable that installs the daisyUI adapter onto the active Theme Kit runtime. Maintains a tagged :root style element with concrete --color-* variables, kept in sync as the active theme changes.

Returns ThemeAdapter<T>

useOpenPropsTheme<T extends ThemeDefinition<string>>(options?): ThemeAdapter<T>

Vue composable that installs the Open Props adapter onto the active Theme Kit runtime. Maintains a tagged :root style element with concrete --brand, --link, --size-* and related variables, kept in sync as the active theme changes.

Returns ThemeAdapter<T>

useShadcnTheme<T extends ThemeDefinition<string>>(options?): ThemeAdapter<T>

Vue composable that installs the shadcn/ui adapter onto the active Theme Kit runtime. Maintains a tagged :root style element with concrete --* variables, kept in sync as the active theme changes.

Call once in your app root:

1import { useShadcnTheme } from "@theme-kit/vue";
2
3function App() {
4  useShadcnTheme();
5  return <YourApp />;
6}

Returns ThemeAdapter<T>

useTheme<T extends ThemeDefinition<string>>(): { family: Ref<string, string>; mode: Ref<ThemeMode, ThemeMode>; setFamily: __type(nextFamily: string): void; setMode: __type(nextMode: ThemeMode): void; theme: Ref<T, T>; toggleTheme: __type(): void }

Returns { family: Ref<string, string>; mode: Ref<ThemeMode, ThemeMode>; setFamily: __type(nextFamily: string): void; setMode: __type(nextMode: ThemeMode): void; theme: Ref<T, T>; toggleTheme: __type(): void }

useThemeBatch(): __type(callback: __type(): void): void

Returns __type(callback: __type(): void): void

useThemeHistory<T extends ThemeDefinition<string>>(): { canRedo: Ref<boolean, boolean>; canUndo: Ref<boolean, boolean>; clear: __type(): void; history: Ref<readonly { theme: UnwrapRef<T>; timestamp: number }[], readonly HistoryEntry<T>[] | readonly { theme: UnwrapRef<T>; timestamp: number }[]>; jump: __type(index: number): void; redo: __type(): void; undo: __type(): void }

Returns { canRedo: Ref<boolean, boolean>; canUndo: Ref<boolean, boolean>; clear: __type(): void; history: Ref<readonly { theme: UnwrapRef<T>; timestamp: number }[], readonly HistoryEntry<T>[] | readonly { theme: UnwrapRef<T>; timestamp: number }[]>; jump: __type(index: number): void; redo: __type(): void; undo: __type(): void }

useThemeLifecycle(): { on: __type(event: keyof ThemeLifecycleEventMap<ThemeDefinition<string>>, listener: __type(data: unknown): void): __type(): void }

Returns { on: __type(event: keyof ThemeLifecycleEventMap<ThemeDefinition<string>>, listener: __type(data: unknown): void): __type(): void }

useThemePacks(): __type(pack: ThemePack<any>): void

Returns __type(pack: ThemePack<any>): void

useThemeRestore(): __type(snapshot: ThemeRuntimeSnapshot<ThemeDefinition<string>>): void

Returns __type(snapshot: ThemeRuntimeSnapshot<ThemeDefinition<string>>): void

useThemeRuntime<T extends ThemeDefinition<string>>(): ThemeRuntime<T>

Returns ThemeRuntime<T>

useThemeSchedule<T extends ThemeDefinition<string>>(): ThemeScheduleController

Reactive access to the runtime's sunrise/sunset scheduling controller.

Requires the runtime (or <ThemeProvider>) to be created with the scheduled option. The returned state ref tracks enabled, status, active, sunrise/sunset and the next transition; enable()/disable() /set() control the engine.

<script setup lang="ts">
const schedule = useThemeSchedule();
</script>

Returns ThemeScheduleController

useThemeSnapshot(): __type(): ThemeRuntimeSnapshot<ThemeDefinition<string>>

Returns __type(): ThemeRuntimeSnapshot<ThemeDefinition<string>>

validateTheme(theme, options?): ValidationResult

Returns ValidationResult

validateThemeContrast(theme, options?): ContrastValidationResult

Returns ContrastValidationResult

Classes

class ThemeError

Extends Error

The default value is 10 but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed.

If set to a non-number value, or set to a negative number, stack traces will not capture any frames. | | captureStackTrace | void | — | | prepareStackTrace | any | — |

class ThemeRegistry<T extends ThemeDefinition>

Interfaces

AccessibilityPluginOptions

AdapterPlugin

AdapterPluginContext

AdapterRegistration

A successful registration returned by AdapterRegistry.use. Calling dispose() removes exactly the adapter instance it was created for — but only when its own reference count drops to zero. This makes composition (React Strict Mode, Svelte lifecycles, nested providers) deterministic.

AdapterRegistry<T extends ThemeDefinition>

The runtime-owned adapter registry. Registering an adapter installs it; the runtime notifies the registry when the active theme changes.

use is idempotent per adapter instance and returns an AdapterRegistration whose dispose() uninstalls deterministically:

const handle = runtime.adapters.use(adapter);
// ... later
handle.dispose();

AnimationsPluginOptions

BroadcastChannelLike<T>

BroadcastPluginOptions

BuildThemeCssMapOptions

CodeTokens

ContrastCheck

ContrastValidationResult

CSSVariablesOptions

DebuggerPluginOptions

DevToolsPluginOptions

DOMBindingOptions

GeneratedThemePair

GenerateThemeOptions

GenerationPluginOptions

HistoryEntry<T extends ThemeDefinition>

HistoryPluginOptions

InitialThemeResolution<T extends ThemeDefinition>

MigrateOptions

MigrationStep

ModuleOptions

MultiWindowSyncOptions

NuxtThemeBootstrapOptions<T extends ThemeDefinition>

OverlayScrollbarHandle

OverlayScrollbarOptions

PersistencePluginOptions

PluginManager<T extends ThemeDefinition>

PresetVariantOverride

ResolvedSolarLocation

ResolveInitialThemeOptions<T extends ThemeDefinition>

ResolveSelectionOptions<T extends ThemeDefinition>

ResolveSelectionThemeOptions<T extends ThemeDefinition>

ResolveThemeFromCookiesOptions<T extends ThemeDefinition>

ScheduledPluginOptions<T extends ThemeDefinition>

ScheduledThemeBindingOptions<T>

ScheduledThemeOptions<T extends ThemeDefinition>

ScheduledThemePairInput<T extends ThemeDefinition>

ScopedThemeBindingOptions

ScopedThemePrePaint

ScopedThemePrePaintOptions

ScrollbarOptionsResolved

Resolved (defaulted) options used internally.

SelectionThemeResolution<T extends ThemeDefinition>

SolarLocationInput

StorageAdapter

SystemThemeBindingOptions<T extends ThemeDefinition>

ThemeAdapter<T extends ThemeDefinition>

The contract every library adapter implements. The runtime only knows this interface — it never knows Bootstrap, MUI, Chakra or any other library.

ThemeAnimationInput

Input consumed by the Animation Coordinator for a single theme change.

ThemeBootstrapScriptOptions<T extends ThemeDefinition>

ThemeBroadcastAdapter

ThemeBroadcastOptions

ThemeChangeEvent<T extends ThemeDefinition>

ThemeDebugger<T extends ThemeDefinition>

ThemeDefinition<Name extends ThemeName>

ThemeDiff

What actually changed between two themes, grouped by token category.

Produced by the Theme Diff Engine. Every downstream stage (planner, scanner, coordinator) keys off these booleans so Theme Kit only animates the token groups that really changed — never a blanket transition.

ThemeHistory<T extends ThemeDefinition>

ThemeHistoryOptions

ThemeInspectorProps

ThemeLifecycle<T extends ThemeDefinition>

ThemeLifecycleEventMap<T extends ThemeDefinition>

ThemeMeta

ThemeModeControllerOptions<T extends ThemeDefinition>

ThemePersistenceAdapter

ThemePersistenceOptions

ThemePlugin<T extends ThemeDefinition>

Extends ThemePluginHooks<T>

ThemePluginHooks<T extends ThemeDefinition>

ThemeProviderProps<T extends ThemeDefinition>

Extends ThemeRuntimeOptions<T>

ThemeRegistryOptions<T extends ThemeDefinition>

ThemeRuntime<T extends ThemeDefinition>

ThemeRuntimeOptions<T extends ThemeDefinition>

Extends ThemeRegistryOptions<T>

ThemeRuntimeSnapshot<T extends ThemeDefinition>

ThemeSchedule

ThemeScheduleOptions<T extends ThemeDefinition>

ThemeScheduleSetOptions

Extends SolarLocationInput

ThemeScheduleState

Reactive snapshot of a ThemeSchedule. Emitted to subscribers whenever the enabled state, applied theme or solar times change.

ThemeScheduleTransition

ThemeScopeProps

ThemeScrollbarProps

Extends OverlayScrollbarOptions

ThemeSelectionBroadcastOptions

ThemeSelectionPersistenceAdapter

ThemeSelectionState

ThemeStore<T extends ThemeDefinition>

ThemeStoreOptions<T extends ThemeDefinition>

ThemeToCSSVariablesOptions

ThemeTokens

ThemeTransitionOptions

TokenRemap

TransitionPlan

The concrete, ready-to-apply transition decided by the Transition Planner.

rootProperties — registered --theme-color-* custom properties animated directly on :root; descendants inherit the interpolated values. elementProperties — real CSS properties (padding, border-radius, …) transitioned on the scanned elements that actually use them.

ValidateThemeContrastOptions

ValidateThemeOptions

ValidationIssue

ValidationResult

Type Aliases

AdapterStrategy

How faithfully an adapter reproduces the target library's native feel.

• exact — only map what Theme Kit defines; change nothing.
• native — behave like the library: derive missing semantic concepts (e.g. success/warning/info) and make small feel adjustments.
• aggressive — fully emulate the library: also adjust spacing, typography, elevation, saturation and contrast.

"exact" | "native" | "aggressive"

AnimatedGroupKey

typeof ANIMATED_GROUP_KEYS[number]

CalculateSunTimesLocationOptions

Options accepted by calculateSunTimes for resolving a location when latitude/longitude are omitted.

SolarLocationInput

CVDType

"protanopia" | "deuteranopia" | "tritanopia" | "achromatopsia"

PrePaintScrollbarOptions

Phase 1 — Bootstrap: hide native scrollbar before first paint.

This is a tiny, dependency-free, blocking <script> that runs before React. It does ONE thing: inject a <style> and add tk-scrollbar to <html> so the native scrollbar is never painted.

No DOM creation. No observers. No listeners. No React. No rAF.

Executes in under 1 ms.

The overlay (ThemeScrollbar) handles everything else: measure, draw, animate, drag, hover, physics. When the overlay has been painted once, it adds tk-scrollbar-ready to <html> — enabling CSS fade-in.

Architecture:

Phase 1 — Bootstrap (this module) └─ hide native scrollbar └─ add tk-scrollbar

Phase 2 — ThemeScrollbar (React / Web / Angular) └─ create overlay └─ measure └─ attach listeners (scroll, resize, pointer, wheel, MutationObserver)

Phase 3 — Ready └─ tk-scrollbar-ready └─ overlay fades in via CSS

Next.js (@theme-kit/next) server-renders the tk-scrollbar class on <html> and inlines createPrePaintScrollbarCSS() as a <style> in <head> when the scrollbar prop is set — so the native bar is hidden from the very first paint AND React hydrates without a class mismatch. Emitting createPrePaintScrollbarScript() yourself is only needed when you're not on @theme-kit/next (no SSR of the class).

void

PresetFamily

"neutral" | "oat" | "berry" | "mint" | "citrus" | "cocoa" | "plum" | "iris" | "sky" | "graphite"

PresetOverrides

Partial<Record<PresetFamily, Partial<Record<PresetVariant, PresetVariantOverride>>>>

PresetThemeName

${unknown}${unknown}

PresetVariant

"light" | "dark"

ScopedThemeSelection

A scoped theme selection. Either an exact theme name (or family name), or an explicit family + mode pair. Provided as a string for convenience — every framework wrapper accepts it.

string | { name: string } | { family: string; mode?: ThemeMode }

ScrollbarArrowDir

Direction of a single arrow button on an axis strip.

"up" | "down" | "left" | "right"

ScrollbarAxis

Scrollbar overlay engine — public options, runtime types and per-host runtime state.

The philosophy: the browser always performs the scrolling. This module only renders a theme-aware, animated overlay that represents the scrollbar. It never replaces or moves native scrolling — it only synchronizes with it.

"vertical" | "horizontal"

ThemeChangeSource

"user" | "system" | "persistence" | "broadcast" | "update" | "init"

ThemeLifecycleEventName

keyof ThemeLifecycleEventMap

ThemeMode

"light" | "dark" | "system"

ThemeName

string

ThemePack<T extends ThemeDefinition>

void

ThemeScheduleStatus

Whether the schedule is driving theme selection right now. "active" means the schedule is enabled and applying its light/dark selection; "disabled" means it has been turned off (e.g. via schedule.disable()).

"active" | "disabled"

TimeZoneLocation

latitude, longitude tuple.

[latitude: number, longitude: number]

TokenGroup

"colors" | "spacing" | "radius" | "shadows" | "borderWidths" | "zIndex" | "breakpoints" | "typography" | "code"

TransitionPreset

"smooth" | "subtle" | "instant" | "custom" | string[]

Variables

ANIMATED_GROUP_KEYS

Token-category → CSS-property classification.

This is the single source of truth for "which token group maps to which CSS property," so the Transition Planner builds transitions from a diff without hardcoding property lists in multiple places.

colors intentionally maps to nothing here: theme colors flow through @property-registered custom properties on :root, so the whole var(--theme-color-*) graph animates by inheritance — no per-element work. Every other group is animated on the scanned elements that use it.

readonly ["colors", "radius", "spacing", "typography", "shadows", "borders", "transforms", "opacity"]

default

NuxtModule<ModuleOptions>

DEFAULT_SCHEDULED_DARK_THEME

"dark"

DEFAULT_SCHEDULED_LIGHT_THEME

The default neutral theme names used when lightTheme/darkTheme are omitted and no family counterpart can be derived.

"light"

DEFAULT_THEME_TRANSITION

Omit<Required<ThemeTransitionOptions>, "preset"> & Partial<Pick<ThemeTransitionOptions, "preset">>

DEFAULT_TIMEZONE_LOCATION

Fallback used when nothing else can be resolved (New York).

TimeZoneLocation

DEFAULT_TRANSITION_PRESET

TransitionPreset

EMPTY_THEME_DIFF

ThemeDiff

EMPTY_THEME_SCHEDULE_STATE

ThemeScheduleState

GROUP_PROPERTIES

Record<AnimatedGroupKey, string[]>

GROUP_VAR_PREFIXES

CSS variable prefixes each token group materializes to (see themeToCSSVariables).

Record<keyof ThemeDiff, string[]>

migrations

MigrationStep[]

PRE_PAINT_SCROLLBAR_CSS

The CSS that hides native scrollbars while tk-scrollbar is present on <html>. Shared by the client bootstrap script and Next's SSR output so both apply identical rules.

string

ThemeInspector

Component & { install: void }

themeKitCookieNames

Cookie contract shared between the server resolver, the client persistence adapter and the blocking bootstrap script. Same names as @theme-kit/next:

theme-name → exact resolved theme theme-family → selected family theme-mode → selected mode (light | dark | system) theme-fingerprint→ theme-config fingerprint (stale cookies are rejected)

{ family: "theme-family"; fingerprint: "theme-fingerprint"; mode: "theme-mode"; name: "theme-name" }