> ## Documentation Index
> Fetch the complete documentation index at: https://docs.overflow.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Theming

> Match every element to your brand with design tokens, size presets, and shadow layers.

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

```javascript theme={null}
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

1. **Size preset** (`appearance.size`). One knob that reshapes chrome and layout density across every element. See [Sizing presets](/payment-elements/theming/sizing-presets).
2. **Design tokens** (`appearance.variables`). Sixteen-plus tokens for color, typography, border, and spacing. See [Token reference](/payment-elements/theming/token-reference).
3. **Shadow layers** (`appearance.shadowSize` plus per-element overrides). Elevation across inputs and buttons. See [Shadows](/payment-elements/theming/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.

```javascript theme={null}
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](/payment-elements/theming/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.

```javascript theme={null}
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](/payment-elements/theming/css-isolation).

## See also

* [Sizing presets](/payment-elements/theming/sizing-presets)
* [Token reference](/payment-elements/theming/token-reference)
* [Element-scoped overrides](/payment-elements/theming/element-scoped-overrides)
* [Shadows](/payment-elements/theming/shadows)
* [CSS isolation](/payment-elements/theming/css-isolation)