Interfaces

CookieOptions

Defined in: react/src/static/types.ts:49 

Cookie security options for theme persistence

Properties

maxAge?

readonly optional maxAge: number

Defined in: react/src/static/types.ts:55 

Max age in seconds. Default: 31536000 (1 year)

path?

readonly optional path: string

Defined in: react/src/static/types.ts:57 

Cookie path. Default: ’/‘

sameSite?

readonly optional sameSite: "Strict" | "Lax" | "None"

Defined in: react/src/static/types.ts:51 

SameSite attribute for CSRF protection. Default: ‘Lax’

secure?

readonly optional secure: boolean

Defined in: react/src/static/types.ts:53 

Force Secure flag. Default: auto-detect from protocol (true on HTTPS)

CreateDynamicThemeProviderOptions

Defined in: react/src/types/index.ts:28 

Options for createDynamicThemeProvider factory function

Type Parameters

T

T extends SchemaDefinition

Properties

schema

readonly schema: Schema<T>

Defined in: react/src/types/index.ts:30 

The schema defining the theme structure

CreateStaticThemeProviderOptions

Defined in: react/src/static/types.ts:14 

Options for createStaticThemeProvider factory function

Type Parameters

TThemes

TThemes extends readonly string[]

Properties

defaultTheme

readonly defaultTheme: TThemes[number]

Defined in: react/src/static/types.ts:20 

Default theme to use as fallback

themes

readonly themes: TThemes

Defined in: react/src/static/types.ts:18 

Array of available theme names (use as const for type inference)

CssVariableOptions

Defined in: core/dist/index.d.ts:175

Options for CSS variable generation

Properties

prefix?

readonly optional prefix: string

Defined in: core/dist/index.d.ts:177

Prefix for CSS variable names (default: none)

separator?

readonly optional separator: string

Defined in: core/dist/index.d.ts:179

Separator between path segments (default: ’-‘)

transformName()?

readonly optional transformName: (path) => string

Defined in: core/dist/index.d.ts:181

Transform function for variable names

Parameters

path

string

Returns

string

DynamicThemeContextValue

Defined in: react/src/types/index.ts:104 

Context value provided by DynamicThemeProvider

Type Parameters

T

T extends SchemaDefinition

Properties

cssVariables

readonly cssVariables: Record<string, string>

Defined in: react/src/types/index.ts:112 

CSS variables as key-value object (empty if not ready)

error

readonly error: Error | null

Defined in: react/src/types/index.ts:128 

The error if state.status === ‘error’, otherwise null

isError

readonly isError: boolean

Defined in: react/src/types/index.ts:126 

state.status === ‘error’

isIdle

readonly isIdle: boolean

Defined in: react/src/types/index.ts:120 

state.status === ‘idle’

isLoading

readonly isLoading: boolean

Defined in: react/src/types/index.ts:122 

state.status === ‘loading’

isReady

readonly isReady: boolean

Defined in: react/src/types/index.ts:124 

state.status === ‘ready’

refresh()

readonly refresh: () => Promise<void>

Defined in: react/src/types/index.ts:114 

Function to manually refresh the theme

Returns

Promise<void>

setThemeId()

readonly setThemeId: (themeId) => void

Defined in: react/src/types/index.ts:110 

Function to change theme ID (triggers fetch)

Parameters

themeId

string

Returns

void

state

readonly state: ThemeState<T>

Defined in: react/src/types/index.ts:106 

Current theme state (discriminated union)

theme

readonly theme: InferTheme<T> | null

Defined in: react/src/types/index.ts:118 

The resolved theme (null if not ready)

themeId

readonly themeId: string

Defined in: react/src/types/index.ts:108 

Current theme identifier

DynamicThemeProviderExports

Defined in: react/src/types/index.ts:134 

Return type of createDynamicThemeProvider factory

Type Parameters

T

T extends SchemaDefinition

Properties

DynamicThemeProvider

readonly DynamicThemeProvider: FC<DynamicThemeProviderProps<T>>

Defined in: react/src/types/index.ts:136 

React context provider component

ThemeContext

readonly ThemeContext: Context<DynamicThemeContextValue<T> | null>

Defined in: react/src/types/index.ts:144 

The underlying React context (for advanced use)

useTheme()

readonly useTheme: () => DynamicThemeContextValue<T>

Defined in: react/src/types/index.ts:138 

Hook to access full theme and metadata

Returns

DynamicThemeContextValue<T>

useThemeReady()

readonly useThemeReady: () => boolean

Defined in: react/src/types/index.ts:142 

Hook to check if theme is ready

Returns

boolean

useThemeValue()

readonly useThemeValue: <P>(path) => PathValue<T, P>

Defined in: react/src/types/index.ts:140 

Hook to access a single theme value by path

Type Parameters

P

P

Parameters

path

P

Returns

PathValue<T, P>

DynamicThemeProviderProps

Defined in: react/src/types/index.ts:55 

Props for the DynamicThemeProvider component

Type Parameters

T

T extends SchemaDefinition

Properties

children

readonly children: ReactNode

Defined in: react/src/types/index.ts:79 

Children

cookieOptions?

readonly optional cookieOptions: CookieOptions

Defined in: react/src/types/index.ts:75 

Cookie security options (only used when persist=‘cookie’)

cssOptions?

readonly optional cssOptions: CssVariableOptions

Defined in: react/src/types/index.ts:69 

CSS variable options (prefix, separator, etc.)

fallback?

readonly optional fallback: ReactNode

Defined in: react/src/types/index.ts:63 

Fallback UI while loading

initialTheme?

readonly optional initialTheme: InferTheme<T>

Defined in: react/src/types/index.ts:61 

Pre-resolved theme for SSR (avoids hydration mismatch)

initialThemeId

readonly initialThemeId: string

Defined in: react/src/types/index.ts:57 

Initial theme identifier - use setThemeId from useTheme() to change

injection?

readonly optional injection: InjectionMode

Defined in: react/src/types/index.ts:67 

CSS injection strategy (default: ‘style-tag’)

nonce?

readonly optional nonce: string

Defined in: react/src/types/index.ts:77 

CSP nonce for style injection (for strict Content Security Policies)

onError()?

readonly optional onError: (error) => void

Defined in: react/src/types/index.ts:65 

Error callback

Parameters

error

Error

Returns

void

persist?

readonly optional persist: PersistMode

Defined in: react/src/types/index.ts:71 

Where to persist theme preference on change (default: ‘none’)

resolver

readonly resolver: ThemeResolver<T>

Defined in: react/src/types/index.ts:59 

Theme resolver from @livery/core

storageKey?

readonly optional storageKey: string

Defined in: react/src/types/index.ts:73 

Storage key name (default: ‘theme’)

Schema

Defined in: core/dist/index.d.ts:96

A validated schema created by createSchema()

Type Parameters

T

T extends SchemaDefinition = SchemaDefinition

Properties

[SCHEMA_BRAND]

readonly [SCHEMA_BRAND]: true

Defined in: core/dist/index.d.ts:97

definition

readonly definition: T

Defined in: core/dist/index.d.ts:98

StaticThemeContextValue

Defined in: react/src/static/types.ts:87 

Context value provided by StaticThemeProvider

Type Parameters

TThemes

TThemes extends readonly string[]

Properties

setTheme()

readonly setTheme: (theme) => void

Defined in: react/src/static/types.ts:91 

Function to change theme

Parameters

theme

TThemes[number]

Returns

void

theme

readonly theme: TThemes[number]

Defined in: react/src/static/types.ts:89 

Current theme name

themes

readonly themes: TThemes

Defined in: react/src/static/types.ts:93 

Array of available theme names

StaticThemeProviderExports

Defined in: react/src/static/types.ts:26 

Return type of createStaticThemeProvider factory

Type Parameters

TThemes

TThemes extends readonly string[]

Properties

StaticThemeProvider

readonly StaticThemeProvider: FC<StaticThemeProviderProps<TThemes>>

Defined in: react/src/static/types.ts:30 

React context provider component

ThemeContext

readonly ThemeContext: Context<StaticThemeContextValue<TThemes> | null>

Defined in: react/src/static/types.ts:34 

The underlying React context (for advanced use)

useTheme()

readonly useTheme: () => StaticThemeContextValue<TThemes>

Defined in: react/src/static/types.ts:32 

Hook to access theme and setTheme

Returns

StaticThemeContextValue<TThemes>

StaticThemeProviderProps

Defined in: react/src/static/types.ts:63 

Props for the StaticThemeProvider component

Type Parameters

TThemes

TThemes extends readonly string[]

Properties

attribute?

readonly optional attribute: string

Defined in: react/src/static/types.ts:73 

DOM attribute to sync (default: ‘data-theme’)

children

readonly children: ReactNode

Defined in: react/src/static/types.ts:65 

Children

cookieOptions?

readonly optional cookieOptions: CookieOptions

Defined in: react/src/static/types.ts:75 

Cookie security options (only used when persist=‘cookie’)

initialTheme?

readonly optional initialTheme: TThemes[number]

Defined in: react/src/static/types.ts:67 

Initial theme for SSR (skips DOM detection)

nonce?

readonly optional nonce: string

Defined in: react/src/static/types.ts:77 

CSP nonce for style injection (for strict Content Security Policies)

persist?

readonly optional persist: PersistMode

Defined in: react/src/static/types.ts:69 

Where to persist theme preference on change (default: ‘localStorage’)

storageKey?

readonly optional storageKey: string

Defined in: react/src/static/types.ts:71 

Storage key name (default: ‘theme’)

ThemeResolver

Defined in: core/dist/index.d.ts:155

A theme resolver instance

Type Parameters

T

T extends SchemaDefinition

Methods

clearCache()

clearCache(): void

Defined in: core/dist/index.d.ts:165

Clear all cached themes

Returns

void

get()

get<P>(params): Promise<PathValue<T, P>>

Defined in: core/dist/index.d.ts:167

Get a value at a specific path

Type Parameters

P

P

Parameters

params

path

P

themeId

string

Returns

Promise<PathValue<T, P>>

invalidate()

invalidate(params): void

Defined in: core/dist/index.d.ts:161

Invalidate cached theme for a theme ID

Parameters

params

themeId

string

Returns

void

resolve()

resolve(params): Promise<InferTheme<T>>

Defined in: core/dist/index.d.ts:157

Resolve theme for a theme ID, using cache if available

Parameters

params

themeId

string

Returns

Promise<InferTheme<T>>

ThemeStoreState

Defined in: react/src/types/index.ts:155 

Internal state shape for the theme store. Uses ThemeState discriminated union for type-safe state management.

Type Parameters

T

T extends SchemaDefinition

Properties

cssVariables

readonly cssVariables: Record<string, string>

Defined in: react/src/types/index.ts:158 

state

readonly state: ThemeState<T>

Defined in: react/src/types/index.ts:156 

themeId

readonly themeId: string | null

Defined in: react/src/types/index.ts:157 

Type Aliases

InferTheme

InferTheme<T> = \{ [K in keyof T]: T[K] extends TokenDefinition ? TokenTypeToValue<T[K]> : T[K] extends SchemaDefinition ? InferTheme<T[K]> : never \}

Defined in: core/dist/index.d.ts:108

Infers the theme type from a schema definition Recursively processes nested groups

Type Parameters

T

T extends SchemaDefinition

InjectionMode

InjectionMode = "style-tag" | "inline" | "none"

Defined in: react/src/types/index.ts:23 

CSS injection strategy for the DynamicThemeProvider

PathValue

PathValue<T, P> = P extends `$\{infer Head\}.$\{infer Tail\}` ? Head extends keyof T ? T[Head] extends SchemaDefinition ? PathValue<T[Head], Tail> : never : never : P extends keyof T ? T[P] extends TokenDefinition ? TokenTypeToValue<T[P]> : T[P] extends SchemaDefinition ? InferTheme<T[P]> : never : never

Defined in: core/dist/index.d.ts:117

Gets the value type at a specific path in the theme

Type Parameters

T

T extends SchemaDefinition

P

P extends string

PersistMode

PersistMode = "localStorage" | "cookie" | "none"

Defined in: react/src/static/types.ts:44 

Persistence strategy for theme preference

SchemaDefinition

SchemaDefinition = object

Defined in: core/dist/index.d.ts:86

A schema definition can contain tokens or nested groups

Index Signature

[key: string]: SchemaDefinition | TokenDefinition

ThemePath

ThemePath<T, Prefix> = \{ [K in keyof T & string]: T[K] extends TokenDefinition ? Prefix extends "" ? K : `$\{Prefix\}.$\{K\}` : T[K] extends SchemaDefinition ? ThemePath<T[K], Prefix extends "" ? K : `$\{Prefix\}.$\{K\}`> : never \}[keyof T & string]

Defined in: core/dist/index.d.ts:113

Helper to extract all valid paths from a schema Returns dot-notation paths like “colors.primary” or “spacing.md”

Type Parameters

T

T extends SchemaDefinition

Prefix

Prefix extends string = ""

ThemeState

ThemeState<T> = { status: "idle"; } | { status: "loading"; } | { status: "ready"; theme: InferTheme<T>; } | { error: Error; status: "error"; }

Defined in: react/src/types/index.ts:95 

Theme state machine - discriminated union ensuring only valid states exist.

Valid states:

• idle: No theme loaded yet, no fetch in progress
• loading: Theme fetch in progress
• ready: Theme successfully loaded
• error: Theme fetch failed

Type Parameters

T

T extends SchemaDefinition

Functions

createDynamicThemeProvider()

createDynamicThemeProvider<T>(options): DynamicThemeProviderExports<T>

Defined in: react/src/provider/create-provider.ts:80 

Creates a fully-typed dynamic theme provider and hooks for a schema.

Use this for themes fetched at runtime from an API or database (e.g., multi-tenant SaaS). The provider handles async fetching, loading states, caching, and error handling.

For static bundled themes (light/dark mode), use createStaticThemeProvider instead.

Type Parameters

T

T extends SchemaDefinition

Parameters

options

CreateDynamicThemeProviderOptions<T>

Options containing the schema

Returns

DynamicThemeProviderExports<T>

Object with DynamicThemeProvider, useTheme, useThemeValue, useThemeReady, and ThemeContext

Example

import { createSchema, t, createResolver } from '@livery/core';
import { createDynamicThemeProvider } from '@livery/react';
 
// Define your schema
const schema = createSchema({
  definition: {
    brand: {
      primary: t.color().default('#3b82f6'),
      secondary: t.color().default('#64748b'),
    },
    spacing: {
      md: t.dimension().default('16px'),
    },
  },
});
 
// Create resolver to fetch themes
const resolver = createResolver({
  schema,
  fetcher: async (themeId) => {
    const res = await fetch(`/api/themes/${themeId}`);
    return res.json();
  },
  cache: { ttl: 60000 },
});
 
// Create typed provider and hooks
const { DynamicThemeProvider, useTheme, useThemeValue } = createDynamicThemeProvider({ schema });
 
// Use in your app
function App() {
  return (
    <DynamicThemeProvider initialThemeId="acme" resolver={resolver}>
      <MyComponent />
    </DynamicThemeProvider>
  );
}
 
function MyComponent() {
  // Full type inference!
  const primary = useThemeValue('brand.primary'); // string
  const { theme, isLoading, setThemeId } = useTheme();
 
  if (isLoading) return <Spinner />;
 
  return <div style={{ color: primary }}>Hello</div>;
}

createStaticThemeProvider()

createStaticThemeProvider<TThemes>(options): StaticThemeProviderExports<TThemes>

Defined in: react/src/static/create-static-provider.ts:57 

Creates a typed StaticThemeProvider and useTheme hook for static themes.

Use this for bundled themes (light/dark mode) where all theme CSS is generated upfront with toCssStringAll(). Theme switching is instant since it just changes the data-theme attribute.

For dynamic themes fetched from an API or database, use createDynamicThemeProvider instead.

Type Parameters

TThemes

TThemes extends readonly string[]

Parameters

options

CreateStaticThemeProviderOptions<TThemes>

Returns

StaticThemeProviderExports<TThemes>

Example

import { toCssStringAll } from '@livery/core';
import { createStaticThemeProvider, getThemeInitScript } from '@livery/react';
 
// 1. Generate CSS (include in <head>)
export const css = toCssStringAll({ schema, themes, defaultTheme: 'light' });
 
// 2. Generate init script (include in <head>)
export const initScript = getThemeInitScript({
  themes: ['light', 'dark'],
  defaultTheme: 'light',
});
 
// 3. Create provider and hook
export const { StaticThemeProvider, useTheme } = createStaticThemeProvider({
  themes: ['light', 'dark'] as const,
  defaultTheme: 'light',
});
 
// In your layout:
// <head>
//   <style dangerouslySetInnerHTML={{ __html: css }} />
//   <script dangerouslySetInnerHTML={{ __html: initScript }} />
// </head>
// <body>
//   <StaticThemeProvider>{children}</StaticThemeProvider>
// </body>