Skip to main content
Every standalone element accepts an appearance field that layers on top of the instance-level theme. Use this when a single page mounts multiple elements and a subset needs different chrome (for example, a card at the default size and a bank field at compact).

Example

Cascade order (deepest wins)

  1. SDK defaults.
  2. Instance appearance.size host class.
  3. Instance appearance.variables inline styles.
  4. Element appearance.size host class (replaces the instance size class on this element only).
  5. Element appearance.variables inline styles.

Merge, not replace

Element variables override instance variables only on per-key conflict. Instance keys absent from the element override are preserved.
appearance.size also wins per element. Setting size: 'compact' on the element swaps the size-preset class on that element’s host; the instance-level size class is removed from that host first.

Runtime updates

Call element.update({ appearance: { variables: { ... } } }) to change tokens without remounting:
The token is written to the host as an inline style. Tokens removed from the config are cleared, so switching themes never leaks stale values.

Composite elements

appearance is not allowed on sub-elements nested inside checkout (or on the fields.fullName slot of billingAddress and 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.

See also

Last modified on July 17, 2026