Theming

Every element reads its chrome from a set of design tokens. Pass a flat appearance object to new Overflow(...) and every mounted element picks it up.

Quickstart

new Overflow('live_pub_...', {
  appearance: {
    size: 'normal',
    shadowSize: 'sm',
    variables: {
      colorPrimary: '#0a3783',
      colorBorder: '#ededed',
      borderRadius: '6px',
      fontFamily: 'Inter, system-ui, sans-serif',
    },
  },
});

Every token is optional. Anything left undefined falls through to sensible defaults.

Three layers

Size preset (appearance.size). One knob that reshapes chrome and layout density across every element. See Sizing presets.
Design tokens (appearance.variables). Sixteen-plus tokens for color, typography, border, and spacing. See Token reference.
Shadow layers (appearance.shadowSize plus per-element overrides). Elevation across inputs and buttons. See Shadows.

Element-scoped overrides

Every standalone element accepts an appearance field that layers on top of the instance theme. Use this when a single page mounts multiple elements and a subset needs different chrome.

overflow.bank({
  appearance: {
    size: 'compact',
    variables: { inputBorderRadius: '0px' },
  },
}).mount('#bank');

The element-level appearance merges with the instance-level appearance on a per-key basis. See Element-scoped overrides.

Composite elements

appearance is not allowed on sub-elements nested inside checkout (or on the fields.fullName slot of billingAddress / shippingAddress). Composite elements are themed as one cohesive visual unit; setting appearance on a nested slot is a TypeScript error. To diverge a sub-element’s chrome, mount it standalone instead.

Runtime updates

Keep the Overflow instance you created; do not construct a new one to change the theme. Update the instance-wide theme with overflow.update({ appearance: { variables: { ... } } }) and every mounted element re-renders with the new tokens. For a one-off override on a single standalone element, call element.update({ appearance: { variables: { ... } } }) instead. Tokens omitted from the new config are cleared from the host, so theme switching never leaks stale values.

const overflow = new Overflow('live_pub_...', {
  appearance: { variables: { colorPrimary: '#0a3783' } },
});

// Later, e.g. on a dark-mode toggle:
overflow.update({
  appearance: { variables: { colorPrimary: '#8ab4ff', colorBackground: '#0b0b0f' } },
});

CSS isolation

Every element renders inside a .overflow-element shadow host. Merchant CSS on the host page cannot leak into element chrome, and element CSS cannot leak out. See CSS isolation.

Get started

Elements

Options

Events

Guides

Theming

Quickstart

Three layers

Element-scoped overrides

Composite elements

Runtime updates

CSS isolation

See also

​Quickstart

​Three layers

​Element-scoped overrides

​Composite elements

​Runtime updates

​CSS isolation

​See also

Quickstart

Three layers

Element-scoped overrides

Composite elements

Runtime updates

CSS isolation

See also