Theming

Templatical ships with a polished default theme. Two ways to override any color, radius, shadow, or font:

CSS variables on the container (--tpl-user-*) — the recommended approach. Works in both shadow DOM (default) and light DOM modes. Pure CSS — no JS round-trip.
ThemeOverrides config (JSON) — pass colors at init() time. Useful when colors come from runtime data (user preference, multi-tenant brand config).

Both approaches can be combined — the ThemeOverrides config takes precedence because it applies as inline styles, which beat class-bound variables.

CSS variables on the container

Set --tpl-user-* variables on the container you pass to init() (or any ancestor). They inherit across the shadow boundary into the editor's root and override the built-in defaults:

html

<div
  id="editor"
  style="
    --tpl-user-primary: oklch(65% 0.2 280);
    --tpl-user-primary-hover: oklch(58% 0.2 280);
    --tpl-user-primary-light: oklch(94% 0.05 280);
    --tpl-user-radius: 14px;
  "
></div>

Or in a stylesheet:

css

#editor {
  --tpl-user-primary: oklch(65% 0.2 280);
  --tpl-user-primary-hover: oklch(58% 0.2 280);
  --tpl-user-primary-light: oklch(94% 0.05 280);
  --tpl-user-radius: 14px;
}

CSS-custom-property inheritance crosses shadow roots, so the variables you set in the host page reach the editor regardless of mount mode. You don't need separate code paths for shadowDom: true vs shadowDom: false.

Light-mode tokens

Every token follows the same shape: declare --tpl-user-<name> on the container to override the SDK default.

Override variable	Purpose
`--tpl-user-bg`	Main background
`--tpl-user-bg-elevated`	Elevated surfaces (panels, dropdowns)
`--tpl-user-bg-hover`	Hover state background
`--tpl-user-bg-active`	Active/pressed state background
`--tpl-user-border`	Default border color
`--tpl-user-border-light`	Subtle border (dividers, separators)
`--tpl-user-text`	Primary text
`--tpl-user-text-muted`	Secondary text
`--tpl-user-text-dim`	Disabled or hint text
`--tpl-user-primary`	Primary brand color (buttons, links)
`--tpl-user-primary-hover`	Primary hover state
`--tpl-user-primary-light`	Primary tinted background
`--tpl-user-secondary`	Secondary accent color
`--tpl-user-secondary-hover`	Secondary hover state
`--tpl-user-secondary-light`	Secondary tinted background
`--tpl-user-success`	Success state color
`--tpl-user-success-light`	Success tinted background
`--tpl-user-warning`	Warning state color
`--tpl-user-warning-light`	Warning tinted background
`--tpl-user-danger`	Danger/error state color
`--tpl-user-danger-light`	Danger tinted background
`--tpl-user-canvas-bg`	Canvas area behind the email template
`--tpl-user-base-size`	Editor UI sizing unit (`16px`) — see Editor size
`--tpl-user-radius`	Default border radius (`10px`)
`--tpl-user-radius-sm`	Small border radius (`7px`)
`--tpl-user-radius-lg`	Large border radius (`14px`)
`--tpl-user-font-family`	UI font stack
`--tpl-user-shadow-sm`	Subtle shadow
`--tpl-user-shadow`	Default shadow
`--tpl-user-shadow-md`	Medium shadow
`--tpl-user-shadow-lg`	Large shadow
`--tpl-user-shadow-xl`	Extra-large shadow
`--tpl-user-overlay`	Modal backdrop overlay
`--tpl-user-ring`	Focus ring
`--tpl-user-transition`	Spring easing transition

Dark-mode tokens

Dark mode uses a parallel --tpl-user-dark-* namespace, so you can theme light and dark independently:

css

#editor {
  /* Light overrides */
  --tpl-user-primary: oklch(65% 0.2 280);

  /* Dark overrides */
  --tpl-user-dark-primary: oklch(75% 0.16 280);
  --tpl-user-dark-bg: oklch(18% 0.005 280);
  --tpl-user-dark-text: oklch(94% 0.005 280);
}

Replace --tpl-user- with --tpl-user-dark- in any token name from the table above to target dark mode. The editor activates dark mode via data-tpl-theme="dark" on its root and reads the dark-namespace defaults; your --tpl-user-dark-* overrides plug in there.

Dark mode is opt-in via the uiTheme config — set 'dark' or 'auto' to enable. See Dark mode below.

Editor size and the host root font-size

The editor's UI sizing — spacing, font sizes, border radii — is anchored to a single base unit, --tpl-user-base-size, which defaults to 16px.

Because the default is a fixed pixel value (not rem), the editor renders at a consistent size regardless of your page's root font-size. If your design system sets a custom html { font-size } — for example 8px to make 1rem = 8px — the editor is unaffected and stays at its intended size. (A rem always resolves against the document root, even inside the editor's shadow root, so without this anchor a custom root font-size would scale the whole editor up or down.)

Scaling the editor up or down

Set --tpl-user-base-size on the container (or any ancestor) to scale the entire editor UI proportionally:

css

#editor {
  --tpl-user-base-size: 18px; /* ~12% larger chrome, text, spacing, radii */
}

css

#editor {
  --tpl-user-base-size: 14px; /* more compact */
}

Any CSS length works. If you prefer the editor to track your custom root font-size after all, set a rem value — e.g. --tpl-user-base-size: 2rem against an 8px root resolves to 16px.

This affects the editor chrome only. The email content on the canvas uses the pixel sizes stored on each block, so your template renders identically no matter how the editor UI is scaled.

The same --tpl-user-base-size knob applies to the standalone @templatical/media-library SDK. Like every --tpl-user-* variable, it works identically in shadow-DOM and light-DOM modes.

ThemeOverrides config

Use the theme field of init() when you need to apply theme overrides programmatically (multi-tenant branding, user preference toggles, etc.):

import { init } from "@templatical/editor";

const editor = await init({
  container: "#editor",
  theme: {
    primary: "#6d28d9",
    primaryHover: "#5b21b6",
    primaryLight: "#ede9fe",
    bg: "#fafafa",
    text: "#1a1a1a",
  },
});

ThemeOverrides is applied as inline styles on the editor's .tpl root, so it wins over the class-bound defaults and over any --tpl-user-* variables you've set on the container.

Available config keys

The JSON keys mirror the CSS variable names (camelCase instead of kebab-case). All keys are optional — unset keys fall back to --tpl-user-* or the built-in default.

Token	Purpose
`bg`	Main background
`bgElevated`	Elevated surfaces
`bgHover`	Hover state background
`bgActive`	Active/pressed state background
`border`	Default border color
`borderLight`	Subtle border
`text`	Primary text
`textMuted`	Secondary text
`textDim`	Disabled or hint text
`primary`	Primary brand color
`primaryHover`	Primary hover state
`primaryLight`	Primary tinted background
`secondary`	Secondary accent color
`secondaryHover`	Secondary hover state
`secondaryLight`	Secondary tinted background
`success`	Success state color
`successLight`	Success tinted background
`warning`	Warning state color
`warningLight`	Warning tinted background
`danger`	Danger/error state color
`dangerLight`	Danger tinted background
`canvasBg`	Canvas area behind the email template

TypeScript type

import type { ThemeOverrides } from "@templatical/types";

Dark mode

The editor supports a dark theme for its UI chrome (header, sidebars, toolbar, modals). Dark mode is independent of the canvas dark-preview toggle, which simulates how emails look in recipients' dark-themed email clients.

Activation

Set uiTheme in the init config. The default is 'auto', which follows the user's system preference via prefers-color-scheme.

const editor = await init({
  container: "#editor",
  uiTheme: "dark", // 'light' | 'dark' | 'auto'
});

Runtime toggle

Switch the theme without re-initializing:

editor.setTheme("dark");
editor.setTheme("light");
editor.setTheme("auto"); // follow system preference

Dark overrides via `ThemeOverrides`

Customize the dark palette separately using the dark key inside theme:

const editor = await init({
  container: "#editor",
  uiTheme: "auto",
  theme: {
    // Light mode overrides
    primary: "#6d28d9",
    primaryHover: "#5b21b6",
    // Dark mode overrides
    dark: {
      primary: "#a78bfa",
      primaryHover: "#c4b5fd",
      bg: "#1e1e2e",
      bgElevated: "#2a2a3c",
    },
  },
});

Priority chain. When dark mode is active, only theme.dark overrides are applied as inline styles. Unset dark tokens fall back through --tpl-user-dark-* (if set on the container) to the built-in dark defaults.

Scenario	What applies
Light mode, no overrides	Built-in light defaults
Light mode, `--tpl-user-*` on container	Container overrides + remaining light defaults
Light mode, `theme` config	`theme` overrides + container `--tpl-user-*` + remaining light defaults
Dark mode, no overrides	Built-in dark defaults
Dark mode, `--tpl-user-dark-*` on container	Container overrides + remaining dark defaults
Dark mode, `theme.dark` config	`theme.dark` overrides + container `--tpl-user-dark-*` + remaining dark defaults

TypeScript types

import type { ThemeOverrides, UiTheme } from "@templatical/types";

// UiTheme = 'light' | 'dark' | 'auto'
// ThemeOverrides includes a `dark?: Omit<ThemeOverrides, 'dark'>` key

Why two override surfaces?

CSS variables on the container are simpler when:

Theme colors are static or known at build time.
You want the same theme tokens to apply to both the editor and your surrounding UI (set them on a shared wrapper).
You're using CSS Modules, Tailwind, or another style system that already deals in CSS variables.

ThemeOverrides JSON is simpler when:

Theme colors come from runtime data (user account preferences, multi-tenant branding).
You're working in a framework that doesn't naturally expose a single styled container element.
You want a single typed API surface and don't want to spell variable names by hand.

Both surfaces compose: container variables provide the default, ThemeOverrides patches specific tokens on top. The editor's theme config option always wins because it applies as inline styles.

Matching your own UI to the editor's theme

If you want your surrounding chrome (e.g. a wrapper toolbar or status bar) to inherit the editor's palette, set the override variables on a wrapper that contains both your UI and the editor, then reference them from both:

html

<div
  class="my-app"
  style="--tpl-user-primary: #6d28d9; --tpl-user-bg: #fafafa;"
>
  <header class="my-app__header">…</header>
  <div id="editor"></div>
</div>

css

.my-app__header {
  background: var(--tpl-user-bg);
  color: var(--tpl-user-primary);
}

In shadow-DOM mode (the default), the editor's internal --tpl-* variables stay inside the shadow root and aren't visible to host CSS. Your host CSS reads from the --tpl-user-* variables you set yourself, so the two stay in sync.

See the Shadow DOM guide for the mechanics of how variables cross the boundary.

Theming ​

CSS variables on the container ​

Light-mode tokens ​

Dark-mode tokens ​

Editor size and the host root font-size ​

Scaling the editor up or down ​

ThemeOverrides config ​

Available config keys ​

TypeScript type ​

Dark mode ​

Activation ​

Runtime toggle ​

Dark overrides via ThemeOverrides ​

TypeScript types ​

Why two override surfaces? ​

Matching your own UI to the editor's theme ​