API reference

Appearance & theming

A small, closed token API mapped to CSS variables. You can't inject arbitrary CSS through it; only the known tokens below are ever emitted.

The Appearance object

interface Appearance {
  variables?: AppearanceVariables;
  radii?: string;
  fontFamily?: string;
  colorScheme?: 'light' | 'dark' | 'auto';
  shadowRoot?: boolean;   // mount inside Shadow DOM (default true)
  loadFonts?: boolean;    // inject brand fonts from Google Fonts (default true)
  layout?: 'inline' | 'floating';
}

colorScheme'light' | 'dark' | 'auto'optional

Light, dark, or follow the system preference.

layout'inline' | 'floating'default: 'inline'optional

'inline' fills the container and paints the cream background. 'floating' anchors to a viewport corner with a transparent background and a very high z-index, a chat-bubble pop-in.

shadowRootbooleandefault: trueoptional

Mount inside a Shadow DOM root so host CSS can’t leak in. Set false if you need the UI in the light DOM.

loadFontsbooleandefault: trueoptional

Inject the brand fonts (Zilla Slab / DM Sans / JetBrains Mono) from Google Fonts. Set false if you self-host them or a CSP blocks fonts.googleapis.com; the SDK falls back to system fonts.

radiistringoptional

Global border-radius override.

fontFamilystringoptional

Override the UI font stack.

Variables

appearance.variables maps friendly names onto the SDK’s internal CSS custom properties. Only these keys are honored:

Key	CSS variable
`colorPrimary`	`--dlg-cherry`
`colorBackground`	`--dlg-cream`
`colorText`	`--dlg-charcoal`
`colorTextSecondary`	`--dlg-charcoal-secondary`
`colorDanger`	`--dlg-recording`
`colorSuccess`	`--dlg-success`
`fontFamily`	`--dlg-font-ui`
`borderRadius`	`--dlg-radius`

tsx

<Interview
  studyId={studyId}
  appearance={{
    variables: {
      colorPrimary: '#B43F7F',
      colorBackground: '#FCFBF9',
      borderRadius: '12px',
    },
  }}
/>

Default tokens

The defaults match the Dialogue mobile palette:

cream:    '#FCFBF9'   banner:    '#F1EEEA'
charcoal: '#1C1917'   cherry:    '#B43F7F'
edge:     '#E0E0E0'   recording: '#E74C3C'   paper: '#FFFFFF'

Locale

Locale is set on <DialogueProvider> (locale prop), not in appearance. 17 locales are supported and the choice locks once the interview is created. Read/observe it at runtime with useLocale().

Because theming is a closed token set, you can’t inject arbitrary CSS through appearance. For deeper customization, drop to the headless layer or copy screens from the shadcn-style registry.