Customize appearance - Elements SDK

Elements ships four built-in themes and a small, safety-checked set of CSS variables and rule overrides — enough to match your brand without opening the card iframe to arbitrary CSS.

Themes

Pass theme when creating Elements, or as part of an appearance update:

const elements = radiumone.elements({
  appearance: { theme: "night" },
});

Theme	Description
`default`	Light, bordered inputs (the baseline look)
`flat`	Underline-only inputs, no border/radius
`minimal`	Filled background, no border until focus
`night`	Dark background and text

Variables

Override individual design tokens on top of a theme:

const elements = radiumone.elements({
  appearance: {
    theme: "default",
    variables: {
      colorPrimary: "#7C3AED",
      fontFamily: "Arial, sans-serif",
      borderRadius: "8px",
    },
  },
});

Variable	Purpose
`colorPrimary`	Accent color (focus ring, etc.)
`colorBackground`	Field background
`colorText`	Input text color
`colorTextPlaceholder`	Placeholder text color
`colorDanger`	Error-state color
`colorSuccess`	Success-state color
`fontFamily`	See “Fonts” below — must resolve to an allowed system stack
`fontSize`, `fontWeight`	Type scale
`spacingUnit`	Base spacing unit
`borderRadius`, `borderWidth`, `borderColor`	Border styling
`focusBorderColor`, `focusBoxShadow`	Focus-state styling
`colorScheme`	`light`, `dark`, or `auto`

Rule overrides

For finer control, target specific field states with rules. Only these 8 selectors are recognized — any other key is silently ignored, not an error: .Input, .Input--focus, .Input--invalid, .Input--complete, .Input--disabled, .Label, .Error, .Icon.

const elements = radiumone.elements({
  appearance: {
    rules: {
      ".Input": { padding: "12px 16px", lineHeight: "1.5" },
      ".Input--focus": { borderColor: "#7C3AED" },
      ".Input--invalid": { borderColor: "#DC2626" },
    },
  },
});

Allowed CSS properties

Category	Properties
Typography	`fontFamily`, `fontSize`, `fontWeight`, `fontStyle`, `lineHeight`, `letterSpacing`, `textAlign`, `textTransform`
Color	`color`, `backgroundColor`
Spacing	`padding`, `paddingTop/Right/Bottom/Left`, `margin`, `marginTop/Right/Bottom/Left`
Border	`border`, `borderWidth`, `borderStyle`, `borderColor`, `borderRadius`, `borderTop/Bottom/Left/Right`
Effects	`boxShadow`, `outline`, `outlineColor`, `outlineWidth`, `outlineOffset`, `transition`
Layout	`width`, `height`, `minHeight`, `maxWidth`

What’s silently dropped

Elements strips anything that could be used to exfiltrate data or hide a field, rather than erroring — check your rendered field if a style doesn’t appear:

Values containing url(), var(), attr(), expression(), paint(), element(), javascript:, or @import.
Sizes (width, height, minHeight, maxWidth, fontSize) below 8px, or unparsable values like calc(...).
Fonts outside the system font allowlist — see “Fonts” below.

Fonts

fontFamily only accepts system font-stack names (for example system-ui, -apple-system, Segoe UI, Roboto, Helvetica Neue, Arial, sans-serif, serif, monospace). Custom web fonts aren’t supported — an unrecognized name falls back to system-ui, sans-serif.

Live updates

Update appearance after creation without remounting:

elements.update({ appearance: { theme: "night" } });
// or on a single element:
card.update({ appearance: { variables: { colorPrimary: "#7C3AED" } } });

update() replaces the whole rule for any selector you pass — it doesn’t merge with the current value, including the theme’s own default for that selector. Pass every property you want the selector to end up with, not just the ones that changed.

Locales

Set a locale at init or per-Elements instance to localize field placeholders and validation messages:

const radiumone = await loadRadiumOne("r1pk_test_YOUR_KEY", { locale: "ja" });

Supported locales: en, zh, zh-TW, ms, id, th, vi, ja, ko. An unrecognized locale falls back to en.

Field-validation messages (change.error.message) follow the locale. The required messages from Elements.getState() and Elements.submit(), and the SDK’s load-timeout message, are always English regardless of locale.

Next steps

Content Security Policy

CSP directives your checkout page needs for Elements.

Introduction

Guides

3D Secure

Handle failures

Errors

Reference

Customize appearance - Elements SDK

Themes

Variables

Rule overrides

Allowed CSS properties

What’s silently dropped

Fonts

Live updates

Locales

Next steps

Content Security Policy

​Themes

​Variables

​Rule overrides

​Allowed CSS properties

​What’s silently dropped

​Fonts

​Live updates

​Locales

​Next steps

Content Security Policy

Themes

Variables

Rule overrides

Allowed CSS properties

What’s silently dropped

Fonts

Live updates

Locales

Next steps