Theming

The SDK exposes a single, layered theming surface through the appearance prop on <ToriiProvider>. Three knobs, in order of increasing specificity:

theme: pick a preset (shadcn or mui), or pass a full Theme object.
variables: override individual design tokens on top of the preset.
elements: override classes or inline styles on named component slots. See Elements & slot overrides.

Each preset bundles a light and a dark token set. The SDK emits both as scoped CSS rules at runtime, so the customer app’s existing .dark class on <html> (the shadcn / Tailwind convention) flips the SDK to dark mode automatically, no theme-prop swap needed when the host toggles dark mode.

Merge order

Appearance is fully consumer-driven. The SDK does not fetch theming from the server; your <ToriiProvider> props are the only source of truth. Resolution per render:

Preset baseline: either the preset named by theme or the embedded Theme object.
variables token overrides layered on top of the baseline. Variables apply to both modes.
elements per-slot overrides applied at render time.

Quick start

import { ToriiProvider } from '@torii-js/torii-react';

<ToriiProvider
  publishableKey="pk_live_…"
  appearance={{
    theme: 'shadcn',
    variables: { primary: '262 83% 58%' },
  }}
>
  <App />
</ToriiProvider>

That’s it: no CSS files, no Tailwind, no className plumbing. The SDK emits its own <style> block scoped to .torii and honors the host app’s dark-mode class.

Theme presets

Two presets, each bundling a light and dark variant. Pick the one that matches your component library:

Name	Use when
`shadcn`	Tailwind / shadcn / Next.js apps. The default.
`mui`	Material UI apps. Roboto, Material palette, 4px radius.

appearance={{ theme: 'mui' }}

If appearance.theme is omitted, the SDK uses shadcn.

You can also pass a Theme object directly if you want a fully custom baseline:

import type { Theme } from '@torii-js/torii-react';

const myTheme: Theme = {
  light: { /* every token required */ },
  dark:  { /* every token required */ },
};

appearance={{ theme: myTheme }}

Per-mode overrides, say, a different primary in dark mode, require the full Theme object route. The variables prop applies to both modes.

You don’t have to hand-author every token. The preset themes themselves are importable from @torii-js/torii-react as shadcnTheme and muiTheme, so you can spread one as a starting point and override just the tokens you care about:

import { shadcnTheme, type Theme } from '@torii-js/torii-react';

const myTheme: Theme = {
  ...shadcnTheme,
  light: { ...shadcnTheme.light, primary: '262 83% 58%' },
};

appearance={{ theme: myTheme }}

Design tokens (`variables`)

Every preset is built out of the same token set. Override any subset with variables:

appearance={{
  theme: 'shadcn',
  variables: {
    primary: '#7c3aed',
    primaryForeground: '#ffffff',
    radius: '0.5rem',
  },
}}

Color tokens accept whatever you have on hand: #hex, rgb(), hsl(), or bare HSL triplets ("H S% L%"). These are equivalent:

variables: { primary: '#7c3aed' }          // hex
variables: { primary: 'rgb(124 58 237)' }  // rgb()
variables: { primary: '262 83% 58%' }      // HSL triplet

Internally the SDK stores every color as an HSL triplet so it can compose opacity (hsl(var(--torii-primary) / 0.25)); your value is converted automatically. Alpha is dropped: tokens are opaque. Non-color tokens (radius, fontSans) take any valid CSS value.

Full token list

Surfaces

Token	CSS var
`background`	`--torii-background`
`foreground`	`--torii-foreground`
`card`	`--torii-card`
`cardForeground`	`--torii-card-foreground`
`popover`	`--torii-popover`
`popoverForeground`	`--torii-popover-foreground`

Semantic colors

Token	CSS var
`primary`	`--torii-primary`
`primaryForeground`	`--torii-primary-foreground`
`secondary`	`--torii-secondary`
`secondaryForeground`	`--torii-secondary-foreground`
`accent`	`--torii-accent`
`accentForeground`	`--torii-accent-foreground`
`muted`	`--torii-muted`
`mutedForeground`	`--torii-muted-foreground`
`destructive`	`--torii-destructive`
`destructiveForeground`	`--torii-destructive-foreground`
`success`	`--torii-success`
`successForeground`	`--torii-success-foreground`
`warning`	`--torii-warning`
`warningForeground`	`--torii-warning-foreground`

Form chrome

Token	CSS var
`border`	`--torii-border`
`input`	`--torii-input`
`ring`	`--torii-ring`

Shape & typography

Token	CSS var	Default (`shadcn`)
`radius`	`--torii-radius`	`0.625rem`
`fontSans`	`--torii-font-sans`	Geist / Inter fallback

CSS-variable fallback

If you prefer plain CSS, every token is also reachable as a CSS custom property under the .torii root:

.torii {
  --torii-primary: 262 83% 58%;
  --torii-radius: 0.5rem;
}

/* The SDK respects `.dark` on any ancestor. */
.dark .torii {
  --torii-primary: 0 0% 98%;
}

This works, but the appearance prop is the recommended path; it is type-checked and survives future token additions. Note: color custom properties set this way must be HSL triplets ("H S% L%"): the hex/rgb() convenience above applies only to the variables prop, since the SDK consumes these vars via hsl(var(--torii-primary)).