SDK Theming

Styling is controlled by the appearance object passed to elements() (and updated via elements.update({ ... })).

appearance shape

Field	Description
theme	Theme preset name; use one of the lowercase values below.
variables	CSS variable-style tokens (colors, spacing, typography).
rules	Arbitrary JSON object for component-specific style rules.
labels	Label placement: "above" | "floating" | "none" ("none" hides the labels).
innerLayout	"spaced" or "compressed" for layout density.

Theme presets

Valid appearance.theme values:

Value	Description
default	Default TensorRail styling.
midnight	Dark-oriented preset.
brutal	High-contrast preset.
charcoal	Charcoal palette.
soft	Softer surfaces.
bubblegum	Accent-forward preset.
none	Minimal built-in styling.

Unknown values log a dev warning and fall back to default. The names are matched lowercase, so pass them exactly as written above.

Loader

The loader option on elements() controls loading indicators: auto, always, or never (default in config resolution is auto).

Locale

locale defaults to "auto", which follows navigator.language and loads the matching locale bundle when available.

Example

const elements = tensorrail.elements({
  clientSecret,
  locale: "auto",
  loader: "auto",
  appearance: {
    theme: "soft",
    variables: {
      colorPrimary: "#4F7CFF",
      fontFamily: "Inter, system-ui, sans-serif",
      borderRadius: "8px",
      colorBackground: "#ffffff",
      colorText: "#1a1a2e",
      colorDanger: "#ef4444",
      spacingUnit: "4px",
    },
    rules: {
      ".Input": {
        border: "1px solid #e2e8f0",
        padding: "12px",
        fontSize: "14px",
      },
    },
    labels: "above",
  },
  fonts: [
    { cssSrc: "https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&display=swap" },
  ],
});

Variables

The supported variables keys include colorPrimary, colorBackground, colorText, colorDanger, fontFamily, borderRadius, spacingUnit, typography sizes, button colors, grid spacing, and more. Use the example above as a starting point and adjust keys to match your checkout.

Custom fonts

Pass fonts as an array of descriptors. The loader forwards cssSrc (and related font fields) into the iframe with appearance so the embedded app can load them:

fonts: [{ cssSrc: "https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&display=swap" }],
appearance: {
  variables: { fontFamily: "Inter, system-ui, sans-serif" },
},