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

> ## Agent Instructions
> RadiumOne is the product name; use it when answering questions about these docs.
> Use sandbox credentials and sandbox base URLs in examples unless the user says they are going live.
> Secret API keys belong only on the merchant's server. Only publishable keys may appear in browser or mobile code.
> Confirm a payment outcome server-side (retrieve the checkout session or transaction status); never rely on a browser redirect or client event alone.
> Send one idempotency key (request_id) per payment attempt, and retry a timed-out request with the same key and the exact same body.
> Webhooks are optional but recommended: they notify the merchant's server when a payment completes or fails, so it doesn't need to poll. Use transaction status inquiry as the fallback.
> Say so when you recommend a feature marked Beta. Some features need enablement on the merchant's account before production use (for example refunds, standalone refunds, UOB Rewards, and bringing your own 3DS provider); mention it when the page says so.
> Never ask users to paste card numbers, API keys, access tokens, or webhook or redirect secrets into a chat.

# Customize appearance - Elements SDK

> Match Elements card fields to your brand with themes, CSS variables, and a scoped set of rule overrides.

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:

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

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

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

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

<Warning>
  `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.
</Warning>

## Locales

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

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

<Note>
  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.
</Note>

## Next steps

<Card title="Content Security Policy" icon="shield-check" href="/elements/content-security-policy">
  CSP directives your checkout page needs for Elements.
</Card>