Theming guide

Control the visual appearance of VINR Elements using the appearance option — themes, custom style tokens, and runtime updates.

Elements live in iframes, so they don't inherit your page CSS. Style them through the appearance option — VINR posts the styles into the iframe and applies them safely without exposing arbitrary CSS to the card capture context.

Themes

Light surface, teal-700 primary, zinc neutrals. Good for most checkout pages and the recommended starting point before applying custom tokens.

appearance: { theme: 'default' }

Custom styles

Override individual design tokens with the styles object. All tokens are optional — unspecified tokens fall back to the active theme.

Prop	Type	Default
`colorPrimary`	`string`	-
`colorSuccess`	`string`	-
`colorError`	`string`	-
`borderRadius`	`string`	-
`fontFamily`	`string`	-
`fontSize`	`string`	-
`spacingUnit`	`string`	-

Combining theme with styles overrides only the tokens you specify — the theme provides the rest:

appearance: {
  theme: 'default',
  styles: {
    colorPrimary: '#0b3b45',
    colorError: '#d80027',
    borderRadius: '8px',
    fontFamily: 'Inter, system-ui, sans-serif',
  },
}

Pass this object to useAsparyxSDK as the SDK-level default, or pass it directly to useAsparyxElement to scope the override to a single element.

Updating styles at runtime

Both the SDK and individual elements support in-place style updates. No remount occurs and the customer's typed input is preserved.

SDK-wide — updates all mounted elements:

sdk.updateAppearance({ theme: 'dark' });

Per-element — overrides appearance for one element only:

element.update({
  appearance: {
    styles: { colorPrimary: '#000000' },
  },
});

This is useful for dark-mode toggles: listen for your application's theme change event, then call sdk.updateAppearance() to keep the elements in sync.

What you can't do

For PCI safety, custom CSS rules, fonts loaded by external URL, and arbitrary HTML are not supported inside the iframes. Stick to the styles tokens described above. Anything beyond that — layout overrides, custom animations, injected markup — must live on your own page wrapping the element container.

Brand-matching tips

Set colorPrimary to your brand's primary action color. This is the most visible token — it affects the focused input border, the Pay button, and any interactive highlight.
Align borderRadius with the inputs on the rest of your form. If your inputs use 4px radius, set Elements to 4px; a mismatch is immediately visible.
Use the font already loaded on your page (e.g. "Inter, system-ui, sans-serif") so there is no flash of a different typeface as the iframe renders.
If you support both light and dark modes, call sdk.updateAppearance() when your app's color scheme changes rather than remounting the elements.

For a complete list of element types and mount options, see the Elements reference.

Themes

Custom styles

Updating styles at runtime

What you can't do

Brand-matching tips

On this page