Skip to content
Toriidocs

Theming

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

  1. theme: pick a preset (shadcn or mui), or pass a full Theme object.
  2. variables: override individual design tokens on top of the preset.
  3. 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.

This holds with no appearance prop at all: an omitted appearance resolves to { theme: 'shadcn' }, and both token blocks ship either way. Adding the prop only changes which palette those blocks carry.

Merge order

Section titled “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:

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

Quick start

Section titled “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

Section titled “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)

Section titled “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

Section titled “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

Section titled “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)).

See also

Section titled “See also”