Customize

This page explains how to customize the Checkout Components, including configuring which payment methods are displayed and styling the components to match your brand.

Filter payment methods

Each component supports only and exclude options to control which payment methods are displayed. You can use one or the other, but not both — the SDK throws an error if both are set.

info

The displayed payment methods are always the intersection of the payment methods configured on your account and any filters you provide. If you specify a payment method that is not enabled on your account, it will not be shown.

Allow-list with `only`

Use only to show specific payment methods and hide everything else. This is useful when you know exactly which methods to offer for a transaction.

const paymentMethodsList = components.create("payment-methods-list", {
    only: ["card", "ideal"]
});

const walletButtons = components.create("wallet-buttons", {
    only: ["applepay"]
});

const cardForm = components.create("card-form", {
    only: ["visa", "mastercard", "amex"]
});

warning

With only, new payment methods added to your account won't appear until you update the list. Use exclude if you want new methods to appear automatically.

Exclude with `exclude`

Use exclude to hide specific payment methods while showing everything else. New payment methods added to your account appear automatically.

const paymentMethodsList = components.create("payment-methods-list", {
    exclude: ["paypal", "trustly"]
});

const walletButtons = components.create("wallet-buttons", {
    exclude: ["googlepay"]
});

const cardForm = components.create("card-form", {
    exclude: ["visa", "amex"]
});

Available payment method IDs

ID	Name
`card`	Credit/Debit card (all brands)
`visa`	Visa
`mastercard`	Mastercard
`amex`	American Express
`applepay`	Apple Pay
`googlepay`	Google Pay
`ideal`	iDEAL
`bancontact`	Bancontact
`paypal`	PayPal
`eps`	EPS
`trustly`	Trustly
`mbway`	MB Way
`mybank`	MyBank
`satispay`	Satispay
`alipay`	Alipay
`wechatpay`	WeChat Pay

Configure Card Form

These options only apply to the Card Form component.

Hide cardholder name

Set showCardholderName to false to hide the "Name on card" field (default: true):

const cardForm = components.create("card-form", {
    showCardholderName: false
});

Rootline accepts card payments without a cardholder name. To hide the "Name on card" field in the Card Form inside the Payment Methods List, use cardOptions.

Configure Payment Methods List

These options only apply to the Payment Methods List component.

info

Apple Pay and Google Pay in the Payment Methods List do not show the native Wallet Buttons. Combine the Payment Methods List with the Wallet Buttons component to display native Apple Pay and Google Pay buttons.

Order payment methods

Use paymentMethodOrder to specify which payment methods appear first:

const paymentMethodsList = components.create("payment-methods-list", {
    paymentMethodOrder: ["card", "ideal", "applepay"]
});

Payment methods in this array are shown first in the specified order. Any other available methods appear after. If you specify payment methods that aren't available, they're ignored.

Control visible items

Use visibleItemsCount to set how many payment methods are visible before "Show more" appears (default: 5):

const paymentMethodsList = components.create("payment-methods-list", {
    visibleItemsCount: 3
});

Pass Card Form options

The Payment Methods List contains its own Card Form. Pass Card Form options to it with cardOptions:

const paymentMethodsList = components.create("payment-methods-list", {
    cardOptions: {
        showCardholderName: false
    }
});

cardOptions accepts the same options as the Card Form: showCardholderName, only and exclude.

Combined example

const paymentMethodsList = components.create("payment-methods-list", {
    exclude: ["paypal"],
    paymentMethodOrder: ["card", "ideal"],
    visibleItemsCount: 4,
    cardOptions: {
        showCardholderName: false
    }
});
paymentMethodsList.mount("#payment-methods-list");

Configure Wallet Buttons

These options only apply to the Wallet Buttons component. Use them to match the Apple Pay and Google Pay buttons to your brand:

const walletButtons = components.create("wallet-buttons", {
    height: 40,
    buttonRadius: 8,
    buttonTheme: {
        applePay: "white-outline",
        googlePay: "white"
    },
    buttonType: {
        applePay: "check-out",
        googlePay: "checkout"
    }
});

Option	Type	Default	Description
`height`	number	`48`	Height of each button in pixels
`buttonRadius`	number	`4`	Border radius of each button in pixels
`buttonTheme`	object	`black` for both wallets	Button color, set per wallet with `applePay` and `googlePay`
`buttonType`	object	`plain` for Apple Pay, `buy` for Google Pay	Button label, set per wallet with `applePay` and `googlePay`

plain shows only the wallet logo. The other types add a label, for example "Buy with" or "Check out with".

Wallet	`buttonTheme` values	`buttonType` values
Apple Pay	`black`, `white`, `white-outline`	`add-money`, `book`, `buy`, `check-out`, `contribute`, `donate`, `order`, `plain`, `reload`, `rent`, `subscribe`, `support`, `tip`, `top-up`
Google Pay	`black`, `white`	`book`, `buy`, `checkout`, `donate`, `order`, `pay`, `plain`, `subscribe`

info

Apple and Google set rules for how their buttons look. Check the Apple Pay and Google Pay brand guidelines before you change the defaults.

Track incomplete card form state

You can listen for sanitized card form change events to detect when a customer has started filling the payment form but has not completed it yet. This can be used to warn before they leave the checkout page. These events do not contain card details, field names, lengths, card brands, or validation error codes.

const cardForm = components.create("card-form");
let canLeaveCheckout = true;

cardForm.on("change", (event) => {
    if (event.type === "form_changed") {
        canLeaveCheckout = event.empty || event.complete;
    }
});

window.addEventListener("beforeunload", (event) => {
    if (canLeaveCheckout) {
        return;
    }

    event.preventDefault();
    event.returnValue = "";
});

cardForm.mount("#card-form");

Localization

The SDK supports multiple languages for form labels, placeholders, validation messages, and error messages. Set the locale option when initializing the SDK. By default the SDK uses 'auto' which sets the language based on the customer's browser settings.

const rootline = new Rootline({
    locale: "de"
});

Supported locales

Locale	Language
`auto`	Automatically sets the language based on the customer's browser settings. If the browser language is not supported, English is used as the default.
`en`	English
`de`	German
`nl`	Dutch
`fr`	French
`es`	Spanish
`pl`	Polish
`sk`	Slovak
`da`	Danish

What gets localized

Card Form labels (Card number, Expiry date, Security code, Name on card)
Placeholder text
Validation error messages
Payment method names in the payment-methods-list
SDK error messages

Customize appearance

The Checkout Components can be styled to match your brand. You can customize colors, fonts, border radii, and more using the appearance configuration.

Setting appearance

Pass the appearance object when initializing components:

const rootline = new Rootline();
const components = rootline.components("checkout", {
    accountPublishableKey: "YOUR_ACCOUNT_PUBLISHABLE_KEY",
    amount: "10.00",
    currency: "EUR",
    appearance: {
        theme: "light",
        variables: {
            colorPrimary: "#007bff",
            colorBackground: "#ffffff",
            controlBorderRadius: "8px"
        }
    }
});

Updating appearance dynamically

You can update the appearance after initialization without remounting components:

components.update({
    appearance: {
        theme: "dark",
        variables: {
            colorPrimary: "#ff5722"
        }
    }
});

Themes

The SDK includes built-in themes that set sensible defaults for all variables:

Theme	Description
`light`	Light background with dark text (default)
`dark`	Dark background with light text

appearance: {
    theme: "dark"
}

Variables

Override individual style properties using variables:

Colors

Variable	Description
`colorPrimary`	Primary button and accent color
`colorPrimaryForeground`	Text color on primary elements
`colorForeground`	Main text color
`colorMutedForeground`	Secondary/muted text color
`colorBackground`	Background color
`colorSuccess`	Success state color
`colorWarning`	Warning state color
`colorError`	Error state color

Colors accept hex (#007bff), rgb (rgb(0, 123, 255)), rgba, hsl, or hsla formats.

appearance: {
    variables: {
        colorPrimary: "#007bff",
        colorError: "#dc3545",
        colorBackground: "#f8f9fa"
    }
}

Border radius

Variable	Description
`controlBorderRadius`	Border radius for input fields and buttons
`panelBorderRadius`	Border radius for panels and cards

Values can be a string with units ("8px", "0.5rem") or a number (interpreted as pixels).

appearance: {
    variables: {
        controlBorderRadius: "8px",
        panelBorderRadius: "12px"
    }
}

Typography

Variable	Description
`fontFamily`	Font family for all text
`fontSizeDefault`	Base font size
`fontSizeSmall`	Small text size
`fontSizeLarge`	Large text size
`fontWeightNormal`	Normal font weight
`fontWeightMedium`	Medium font weight

Font sizes accept strings with units ("16px", "1rem") or numbers (interpreted as pixels). Font weights accept numbers (400, 500) or keywords ("normal", "bold").

appearance: {
    variables: {
        fontFamily: "'Inter', sans-serif",
        fontSizeDefault: "16px",
        fontWeightMedium: 500
    }
}

Custom fonts

Load custom fonts using file entries in the fonts array. Each entry points to a font file and declares its weight and style. The file can be hosted on the SDK origin or any HTTPS domain.

Legacy type: "css" font entries are ignored with a warning, so they do not prevent the components from loading.

The weight field accepts a number, such as 400, or an array, such as [400, 500, 700], when one file provides multiple weights. Arrays accept 1–10 weights between 100 and 900. Omit weight to use 400. The generator combines weights that use the same file into one entry; different files require separate entries. The SDK accepts up to 10 font entries.

Paste a Google Fonts CSS URL into the generator, or select font families and weights. It converts the selection into file entries. The URL is used only to choose fonts; the generated configuration does not load Google's CSS endpoint.

Generate a file font configuration

Find font families or paste a Google Fonts CSS URL. The generated configuration loads normal WOFF2 font files; italic variants in pasted URLs are omitted.

Loading font catalog…

Find a font family

Popular fonts:

Customize

Filter payment methods

Allow-list with only

Exclude with exclude

Available payment method IDs

Configure Card Form

Hide cardholder name

Configure Payment Methods List

Order payment methods

Control visible items

Pass Card Form options

Combined example

Configure Wallet Buttons

Track incomplete card form state

Localization

Supported locales

What gets localized

Customize appearance

Setting appearance

Updating appearance dynamically

Themes

Variables

Colors

Border radius

Typography

Custom fonts

Generate a file font configuration

Allow-list with `only`

Exclude with `exclude`