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)
- SDK defaults.
- Instance
appearance.size host class.
- Instance
appearance.variables inline styles.
- Element
appearance.size host class (replaces the instance size class on this element only).
- 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