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"]
});

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"]
});

Available payment method IDs

ID	Name
`card`	Credit/Debit card (all brands)
`visa`	Visa
`mastercard`	Mastercard
`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 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
});

Combined example

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

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

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 the fonts array. The SDK supports two methods:

CSS fonts (recommended)

Load fonts from a CSS URL, such as Google Fonts:

appearance: {
    fonts: [
        {
            type: "css",
            href: "https://fonts.googleapis.com/css2?family=Roboto:wght@400;500&display=swap"
        }
    ],
    variables: {
        fontFamily: "'Roboto', sans-serif"
    }
}

File fonts

Load self-hosted font files:

appearance: {
    fonts: [
        {
            type: "file",
            family: "CustomFont",
            src: "https://your-domain.com/fonts/custom.woff2",
            weight: 400,
            style: "normal"
        }
    ],
    variables: {
        fontFamily: "'CustomFont', sans-serif"
    }
}

warning

Font URLs must use HTTPS.

Complete example

const rootline = new Rootline();
const components = rootline.components("checkout", {
    accountPublishableKey: "YOUR_ACCOUNT_PUBLISHABLE_KEY",
    amount: "10.00",
    currency: "EUR",
    appearance: {
        theme: "light",
        fonts: [
            {
                type: "css",
                href: "https://fonts.googleapis.com/css2?family=Inter:wght@400;500&display=swap"
            }
        ],
        variables: {
            // Colors
            colorPrimary: "#6366f1",
            colorPrimaryForeground: "#ffffff",
            colorForeground: "#1f2937",
            colorMutedForeground: "#6b7280",
            colorBackground: "#ffffff",
            colorError: "#ef4444",

            // Border radius
            controlBorderRadius: "8px",
            panelBorderRadius: "12px",

            // Typography
            fontFamily: "'Inter', sans-serif",
            fontSizeDefault: "16px",
            fontWeightNormal: 400,
            fontWeightMedium: 500
        }
    }
});

Filter payment methods​

Allow-list with only​

Exclude with exclude​

Available payment method IDs​

Configure Payment Methods List​

Order payment methods​

Control visible items​

Combined example​

Localization​

Supported locales​

What gets localized​

Customize appearance​

Setting appearance​

Updating appearance dynamically​

Themes​

Variables​

Colors​

Border radius​

Typography​

Custom fonts​

CSS fonts (recommended)​

File fonts​

Complete example​