Appearance API (Beta)

The Appearance API is the stable beta v1 surface for styling every piece of UI rendered by the Revup SDK: the parent-page container, payment-method buttons, the card form iframe, and overlay states. You pass a single appearance object to revup.init({ appearance }).

The current contract is composed from a theme preset, optional variables overrides, and optional rules for allowlisted abstract targets. Public token names, emitted CSS variable names, and rule-target keys are part of the v1 API and should be treated as stable.

Beta

This is the beta version and is subject to changes and corrections. Although it has been subjected to strict testing and rigorous reviews, there may be certain minimal inconsistencies in meanings and hierarchies. Any feedback will be of great help.

Quick start

const revup = new Revup({ apiKey: 'pk_live_...', orderId: 'order_123' });

await revup.init({
  containerId: 'checkout',
  appearance: {
    theme: 'default',
    variables: {
      backgroundColor: '#000000',
      submitButtonBackgroundColor: '#7B8CDE',
      inputBorderColorFocus: '#7B8CDE',
    },
    rules: {
      '.InputWrapper--focused': {
        'border-width': '2px',
      },
    },
  },
});

How it works

The Appearance API has three inputs:

appearance
├── theme     — preset base ('default' | 'dark' | 'flat' | 'minimal')
├── variables — domain-grouped design tokens
└── rules     — per-element CSS overrides for allowlisted abstract targets

Every resolved variable is emitted on the host page as --revup-<kebab-case-token>. Parent-page rule targets are injected into the merchant page, while iframe rule targets are injected into the card form iframe. The host and iframe surfaces share one resolved appearance object, but each render context has its own target map and managed style tag.

Runtime behavior

The SDK resolves theme. Unknown theme ids fall back to default.
variables are merged on top of the theme preset.
Numeric tokens are clamped to their supported ranges. Padding and border-radius shorthands are expanded before clamping.
String-valued variables are sanitized. Invalid values are dropped and the SDK logs a console warning.
rules are sanitized. Unknown targets, disallowed properties, and invalid values are dropped silently.
The SDK emits host CSS custom properties, applies parent-page rules through a managed <style> tag, and forwards the resolved appearance into the iframe projection path.
Re-initializing the SDK clears previously emitted host CSS variables and replaces the managed appearance rule tags, so the latest configuration fully wins.

Theme presets

The default preset is the only preset that assigns a value to every token. The other presets inherit from default and override only the entries that differ.

For the exact current preset values, inspect APPEARANCE_THEME_PRESETS in the SDK source. APPEARANCE_THEME_PRESETS.default is the source of inherited values for the other three presets.

PRESET	DESCRIPTION
default	Light baseline preset with violet primary (`#8E54E9`), white surfaces, 8 px radius, and Plus Jakarta Sans typography. This is the inheritance source for all other presets.
dark	Dark surfaces, light text, dark input backgrounds, and a lavender submit-button accent.
flat	Minimal borders and flatter surfaces. Focus styling prefers outline over box-shadow.
minimal	Reduced chrome, sharp corners, transparent borders, lighter shadows, and animations disabled.

Variables

Variables are domain-grouped design tokens. The current public surface is organized by functional area.

Foundation (Global)

fontFamily, fontWeightRegular, fontWeightBold, disableAnimations, transitionDuration

Parent Container Layout

backgroundColor, textColor, width, height, maxWidth, padding, borderRadius, justifyContent, alignItems

Form Container (Parent Wrapper)

formBackgroundColor, formPadding, formBorderRadius

Payment Methods Section — Container Layout

paymentMethodsContainerPadding, primaryGridGap

Payment Methods Section — Payment Method Rows & Buttons

paymentMethodHeight, paymentMethodBorderWidth, paymentMethodBorderRadius, paymentMethodBackgroundColor, paymentMethodBorderColor, paymentMethodBoxShadow

Card Button

cardButtonBackgroundColor, cardButtonTextColor, cardButtonBorderColor, cardButtonBorderWidth, cardButtonBorderRadius, cardButtonFontSize, cardButtonFontWeight, cardButtonPadding

cardButtonBackgroundColorHover, cardButtonBorderColorHover, cardButtonTextColorHover

cardButtonBackgroundColorOpen, cardButtonTextColorOpen, cardButtonBorderColorOpen

Card Badge

cardBadgeBackgroundColor, cardBadgeTextColor, cardBadgeFontSize, cardBadgeFontWeight, cardBadgeLetterSpacing, cardBadgeBorderRadius, cardBadgePadding

cardBadgeBackgroundColorOpen, cardBadgeTextColorOpen

Secondary Divider (Other Methods Section)

secondaryGridGap, secondaryDividerColor, secondaryDividerThickness

secondaryDividerLabelTextColor, secondaryDividerLabelBackgroundColor, secondaryDividerLabelFontSize, secondaryDividerLabelPadding, secondaryDividerLabelFontWeight

Other Methods Panel & Toggle

otherGridGap, otherToggleTextColor, otherToggleTextColorHover, otherToggleFontSize, otherToggleFontWeight

Form Fields (Iframe) — Field Container

fieldMinHeight, expiryCvcRowGap

Form Fields (Iframe) — Label

labelTextColor, labelFontSize, labelFontWeight, labelTextColorFocus, labelTextColorInvalid

Form Fields (Iframe) — Input

inputHeight, inputFontSize, inputPadding

inputBorderColor, inputBorderWidth, inputBorderRadius

inputBackgroundColor, inputTextColor, inputBoxShadow

inputPlaceholderColor

inputBackgroundColorHover, inputBorderColorHover

inputBackgroundColorFocus, inputBorderColorFocus, inputBoxShadowFocus, inputOutlineFocus

inputBorderColorInvalid, inputBackgroundColorInvalid

inputBackgroundColorDisabled, inputTextColorDisabled

Form Fields (Iframe) — Input Adornment

inputAdornmentColor

Form Fields (Iframe) — Error Text

errorTextColor, errorFontSize, errorFontWeight

Form Controls — Submit Button

submitButtonHeight, submitButtonBorderRadius

submitButtonBackgroundColor, submitButtonTextColor, submitButtonFontSize, submitButtonFontWeight

submitButtonBackgroundColorHover, submitButtonTextColorHover

submitButtonBackgroundColorActive

submitButtonBackgroundColorDisabled, submitButtonTextColorDisabled, submitButtonOpacityDisabled

Visual Effects — Skeleton

skeletonBackgroundColor, skeletonShimmerColor, skeletonAnimationDuration

Visual Effects — Overlay

overlayLoadingBackgroundColor, overlayDisabledBackgroundColor

Important runtime details

Fallback behavior

secondaryDividerLabelBackgroundColor falls back to backgroundColor when omitted.
labelTextColorFocus falls back to inputBorderColorFocus inside the form projection when not set explicitly.
inputBackgroundColorHover and inputBackgroundColorFocus fall back to inputBackgroundColor when omitted.

Scope & projection

textColor controls host-container text, while inputTextColor controls input text inside the iframe.
inputAdornmentColor is the dedicated color token for icons and adornments inside inputs.
formBackgroundColor, formPadding, and formBorderRadius style the parent wrapper around the iframe. The iframe still receives its own appearance projection from the resolved variables.

Rule targets

rules accepts only allowlisted abstract targets. The SDK maps these keys to concrete selectors internally; raw CSS selectors are not accepted.

There are 53 allowlisted abstract targets in total: 25 for the iframe and 28 for the parent page.

Iframe targets

TARGET	MAPS TO
`.Field`	Field row container
`.Field--focused`	Field row while any descendant is focused
`.Field--invalid`	Field row in invalid state
`.Label`	Field label
`.Label--focused`	Label while focused
`.Label--invalid`	Label in invalid state
`.InputWrapper`	Visual input frame
`.InputWrapper--hover`	Hover state of the input frame, excluding focus and invalid
`.InputWrapper--focused`	Focus state of the input frame, excluding invalid
`.InputWrapper--invalid`	Invalid input frame
`.InputWrapper--disabled`	Disabled input frame
`.Input`	Native input element
`.Input::placeholder`	Input placeholder text
`.InputAdornment`	Adornment or icon inside the input wrapper
`.Error`	Field error text
`.SubmitButton`	Pay button inside the form
`.SubmitButton--hover`	Hover state of the pay button
`.SubmitButton--active`	Active state of the pay button
`.SubmitButton--disabled`	Disabled state of the pay button
`.FormContainer`	Outer wrapper inside the iframe
`.Select`	Native select element
`.Select--hover`	Hover state of the select, excluding focus and invalid
`.Select--focused`	Focus state of the select, excluding invalid
`.Select--invalid`	Invalid select element
`.Select--disabled`	Disabled select element

Parent-page targets

TARGET	MAPS TO
`.RevupContainer`	Outermost SDK container on the merchant page
`.PaymentMethodsContainer`	Stacked payment methods container
`.PaymentMethod--primary`	Primary payment methods only (non-card, non-secondary, non-other)
`.PaymentMethod--card`	Card payment method row
`.PaymentMethod--secondary`	Secondary payment methods (Apple Pay, Google Pay, etc.)
`.PaymentMethod--other`	Other/additional payment methods
`.FormContainerSlot`	Parent wrapper around the form iframe
`.PaymentMethod`	Each rendered payment method row
`.PaymentMethodSkeleton`	Payment method skeleton content
`.CardButton`	Card accordion button
`.CardButton--hover`	Card button hover state
`.CardButton--open`	Card button while the form is expanded
`.CardBrandSlot`	Card brand/logo slot
`.CardBrandIcon`	Card brand/logo icon
`.CardBadge`	Badge on the card button
`.CardBadge--open`	Badge while the form is expanded
`.SecondarySection`	Secondary payment-method section wrapper
`.SecondaryDivider`	Divider line above the secondary grid
`.SecondaryDividerLabel`	Divider label
`.SecondaryGrid`	Compact secondary APM grid
`.OtherSection`	Other/additional payment methods section wrapper
`.OtherToggle`	Toggle for additional payment methods
`.OtherToggle--hover`	Hover state of the additional-methods toggle
`.OtherPanel`	Expandable panel of additional payment methods
`.OtherPanel--open`	Expanded state of the additional-methods panel
`.LoaderSpinner`	Loading spinner element
`.LoaderOverlay`	Loading overlay
`.DisabledOverlay`	Disabled overlay

Sanitization policy

Rules are default-deny. A declaration is kept only when:

The target is allowlisted
The property name matches /^-?[a-zA-Z][a-zA-Z0-9-]*$/
The property is in the SDK allowlist
The value passes sanitization

Allowed properties by category

CATEGORY	ALLOWED PROPERTIES
Color and background	`color`, `background-color`, `background`
Border and corners	`border`, `border-color`, `border-width`, `border-style`, `border-radius`, per-side border color and width, per-corner border radius
Effects	`box-shadow`, `outline`, `outline-color`, `outline-width`, `outline-style`, `opacity`, `backdrop-filter`, `filter`, `text-shadow`
Typography	`font-family`, `font-size`, `font-weight`, `font-style`, `line-height`, `letter-spacing`, `text-align`, `text-decoration`, `text-decoration-color`, `text-decoration-style`, `text-decoration-thickness`, `text-transform`, `text-underline-offset`, `text-overflow`, `white-space`, `word-break`, `word-wrap`, `vertical-align`
Spacing and sizing	`padding`, `margin`, `width`, `height`, `min-width`, `min-height`, `max-width`, `max-height`, `aspect-ratio`, `box-sizing`
Layout	`display`, `align-items`, `justify-content`, `gap`, `flex`, `flex-direction`, `flex-wrap`, `grid-template-columns`, `grid-template-rows`, `grid-gap`, `column-gap`, `row-gap`, `position`, `top`, `right`, `bottom`, `left`, `z-index`, `overflow`, `overflow-x`, `overflow-y`
Interaction and motion	`appearance`, `-webkit-appearance`, `pointer-events`, `user-select`, `cursor`, `transform`, `transform-origin`, `transition`, `transition-duration`, `transition-timing-function`, `transition-property`, `transition-delay`, `animation`, `animation-duration`, `animation-timing-function`, `animation-delay`, `animation-iteration-count`, `animation-name`

Values are rejected when they are empty, longer than 500 characters, contain control characters, contain !important, contain HTML tags, or normalize to dangerous functions and schemes such as url(), image(), image-set(), -webkit-image-set(), cross-fade(), -webkit-cross-fade(), element(), paint(), src(), attr(), expression(), behavior(), -moz-binding, javascript:, vbscript:, data:, @import, @charset, or @namespace.

CSS escapes and comments are normalized before blocklist checks. After declaration-breakout characters are stripped, the blocklist is applied again. Invalid variables are dropped with a console warning; invalid rules are dropped silently. Per target, the first 100 accepted declarations are kept.

Numeric clamping

Numeric tokens are clamped, not rejected. Dimensional tokens are documented as pixel strings. Padding and border-radius shorthands are expanded to explicit values before each side or corner is clamped.

TOKEN GROUP	BOUNDS	APPLIES TO
Payment-method row height	44–55 px	`paymentMethodHeight`
Payment method button styling	0–10 px (border widths), 0–60 px (border radius)	`paymentMethodBorderWidth`, `paymentMethodBorderRadius`
Border radius	0–60 px	`borderRadius`, `formBorderRadius`, `cardButtonBorderRadius`, `cardBadgeBorderRadius`, `inputBorderRadius`, `submitButtonBorderRadius`
Control heights	30–60 px	`inputHeight`, `submitButtonHeight`
Font sizes	8–32 px	`cardButtonFontSize`, `cardBadgeFontSize`, `inputFontSize`, `submitButtonFontSize`, `labelFontSize`, `errorFontSize`, `secondaryDividerLabelFontSize`, `otherToggleFontSize`
Font weights	1–1000	`fontWeightRegular`, `fontWeightBold`, `cardButtonFontWeight`, `cardBadgeFontWeight`, `submitButtonFontWeight`, `labelFontWeight`, `errorFontWeight`, `otherToggleFontWeight`, `secondaryDividerLabelFontWeight`
Gaps	0–40 px	`primaryGridGap`, `secondaryGridGap`, `otherGridGap`, `expiryCvcRowGap`
Padding shorthands	0–40 px per side	`cardButtonPadding`, `cardBadgePadding`, `inputPadding`, `secondaryDividerLabelPadding`
Field minimum height	40–200 px	`fieldMinHeight`
Border widths and divider thickness	0–10 px	`cardButtonBorderWidth`, `inputBorderWidth`, `secondaryDividerThickness`
Disabled submit opacity	0–1	`submitButtonOpacityDisabled`

Public exports

EXPORT	KIND	PURPOSE
`Appearance`	type	Top-level config object with `theme`, `variables`, and `rules`
`AppearanceTheme`	type	Theme preset id: `default`, `dark`, `flat`, `minimal`
`AppearanceVariables`	type	Domain-grouped appearance token bag
`AppearanceRuleTarget`	type	Union of the allowlisted abstract rule targets
`AppearanceRules`	type	`Partial<Record<AppearanceRuleTarget, Record<string, string>>>`
`APPEARANCE_RULE_TARGETS`	runtime set	Use to validate rule keys at runtime
`APPEARANCE_THEME_PRESETS`	runtime record	Built-in preset values
`MIN_BUTTON_HEIGHT`	runtime number	Lower bound for `paymentMethodHeight`
`MAX_BUTTON_HEIGHT`	runtime number	Upper bound for `paymentMethodHeight`
`MIN_BORDER_RADIUS`	runtime number	Lower bound for border-radius tokens
`MAX_BORDER_RADIUS`	runtime number	Upper bound for border-radius tokens

Precedence

rules win within their render context.
variables override the theme preset and are emitted as host CSS custom properties.
Theme preset provides the base token values.
Built-in component defaults remain as fallbacks for anything not set by the preset or variables.

Quick start​

How it works​

Runtime behavior​

Theme presets​

Variables​

Foundation (Global)​

Parent Container Layout​

Form Container (Parent Wrapper)​

Payment Methods Section — Container Layout​

Payment Methods Section — Payment Method Rows & Buttons​

Card Button​

Card Badge​

Secondary Divider (Other Methods Section)​

Other Methods Panel & Toggle​

Form Fields (Iframe) — Field Container​

Form Fields (Iframe) — Label​

Form Fields (Iframe) — Input​

Form Fields (Iframe) — Input Adornment​

Form Fields (Iframe) — Error Text​

Form Controls — Submit Button​

Visual Effects — Skeleton​

Visual Effects — Overlay​

Important runtime details​

Fallback behavior​

Scope & projection​

Rule targets​

Iframe targets​

Parent-page targets​

Sanitization policy​

Allowed properties by category​

Numeric clamping​

Public exports​

Precedence​