Theming

View as Markdown Open in ChatGPT Open in Claude

The SDK supports white-label theming through the theme option on Checktiv.init() and Checktiv.mount(). Theming is set in your frontend code at initialization time and threads into the modules you mount automatically.

There is no console-persisted theme in the current version. Set theming in your init() call; it applies to every module mounted from that client instance.

Brand your own page and layout around the SDK embed for logos and full custom styling. The theme object controls the color inside the surfaces the SDK renders.

Available theme options

Checktiv.init({
  publishableKey: 'ah_pk_us_test_...',
  getSessionToken: async (ctx) => {
    /* ... */
  },
  theme: {
    primaryColor: '#0b5fff', // hex color; defaults to the platform blue
  },
});

Option	Type	Description
`primaryColor`	`string`	Hex color string (e.g. `#0b5fff`). Applied to primary buttons, progress indicators, and focus rings inside the capture journey, inside the credit history screens, inside the e-signature signing frame, and on the e-signature module’s own panels in your page.

How theming is applied

When the SDK mounts a module, it passes theme to that module’s hosted surface at init. The surface applies the values as CSS custom properties inside its sandboxed iframe. Your page’s CSS does not reach the capture UI or the credit history screens, because each of those renders in a sandboxed frame rather than in your own document, so all of their styling has to go through the theme object.

primaryColor is the only theme option, and that is deliberate. It is not widened by any module.

The e-signature module has a second surface

./esign renders on two planes, and theme reaches both. The document renders in a hosted frame, exactly like capture. The module also paints controls directly into your page: the per-document download control and the state panel that carries preparing, the recovery states and the terminal states. Those are plain DOM in your own document, not a shadow root, so your page’s own inherited text color and font do reach them, and the module stamps data-checktiv-esign-* attributes on them for you to target. Setting primaryColor brands both planes together; before it did, an integrator got a branded signing frame beside an unbranded panel. See The e-signature module for the attribute list.

Light and dark mode

The capture screen, the credit history screens, and the signing surface each match light or dark by themselves. They read the color mode from your page in this order:

The data-theme attribute on the <html> element, when it is set to light or dark.
The operating system setting (prefers-color-scheme), when data-theme is not set.

Set data-theme on your <html> element to match the mode your page shows. This keeps the SDK’s surfaces and your page in the same mode. To follow the operating system, leave data-theme unset.

The capture screen and the credit history screens read the mode once, when the module mounts. If your page flips its own light/dark state afterwards, remount the module to bring them with it.

The e-signature module goes further and watches for changes, on both triggers: the operating-system preference flipping, and your own <html data-theme> being mutated. If your page has a light/dark toggle, the signing surface follows it without a remount.

// Mirror your page's own light/dark state onto data-theme so the capture screen
// matches it. (To follow the operating system instead, do not set data-theme at
// all; the SDK then reads prefers-color-scheme.)
const pageIsDark = document.documentElement.classList.contains('dark');
document.documentElement.dataset.theme = pageIsDark ? 'dark' : 'light';

data-theme controls light and dark. primaryColor controls the brand color. Set both to match your page.

Example: matching your app’s brand

import { init } from '@checktiv/sdk-web';
import '@checktiv/sdk-web/idv'; // registers the IDV module that mountProvisioned renders

const client = init({
  publishableKey: 'ah_pk_us_test_...',
  getSessionToken: async (ctx) => {
    const res = await fetch('/api/checktiv/token', { method: 'POST' });
    return (await res.json()).token;
  },
  theme: {
    primaryColor: '#6200ee',
  },
});

client.mountProvisioned({ target: document.getElementById('idv-container') });

Quickstart - end-to-end integration including theming
React - pass theme through <ChecktivJourney> or <ChecktivProvider>
Modules overview - the e-signature module’s two planes and its styling hooks