Appearance

Odus Checkout SDK lets you customize colors, fonts, button labels, field layout, and the set of supported payment methods through the appearance configuration option.

The appearance object has three root properties:

Property	Type	Description
`additionalPaymentMethods`	AdditionalPaymentMethods	Configures how alternative payment methods, such as PayPal and Apple Pay, are displayed in the checkout
`styles`	Styles	Customize colors, fonts, and other visual aspects of the checkout form
`layout`	Layout	Customize text labels and layout options in the checkout form

Example appearance configuration:

const checkout = new OdusCheckout({
  // ... other configuration options
  appearance: {
    additionalPaymentMethods: {
      paypal: {
        enabled: true,
        order: 1,
        countries: ['US', 'GB', 'DE'],
      },
      applePay: {
        enabled: true,
        order: 2,
        displayName: 'Your Store Name',

        countries: ['US', 'GB'],
      },
    },
    styles: {
      borderRadius: 5,
      buttonColor: '#5469d4',
      buttonFontSize: 16,
      buttonTextColor: '#ffffff',
      fontFamily: 'Inter',
      fontSize: 14,
      textColor: '#1a1a1a',
    },
    layout: {
      actionButton: {
        translationKey: 'getPlan',
      },
      phoneNumber: {
        enabled: true,
        label: 'Phone Number',
        defaultCountry: 'LT',
        allowedCountries: ['US', 'GB', 'LT'],
      },
    },
  },
});

Additional Payment Methods

important

Additional payment methods will only be shown after the payment has been associated via the associatePayment method. Before that, a placeholder will be shown instead.

Each additional payment method can be enabled or disabled individually, and you can also specify the order in which they appear. For Apple Pay, you can customize the name that will be shown in the Apple Pay payment sheet via the displayName option.

It is important to understand what this configuration does and does not do:

Regional restrictions and browser support still apply. For example, Apple Pay will only be shown to customers using Safari on supported devices.
If the associated payment does not support a payment method configured in additionalPaymentMethods, that method will not be shown in the checkout. The same applies if the associated payment supports a payment method not listed in additionalPaymentMethods — it also will not be shown.

The list of currently supported additional payment methods includes:

PayPal
Apple Pay

Supported properties for additionalPaymentMethods:

Property	Type	Description
`paypal.enabled`	boolean	Whether PayPal is enabled as a payment method
`paypal.order`	number	Order of PayPal button among other additional payment methods
`paypal.countries`	string[]	Optional array of ISO country codes where PayPal is available (e.g., `["US", "LT"]`)
`applePay.enabled`	boolean	Whether Apple Pay is enabled as a payment method
`applePay.order`	number	Order of Apple Pay button among other additional payment methods
`applePay.displayName`	string	The name shown in the Apple Pay payment sheet
`applePay.countries`	string[]	Optional array of ISO country codes where Apple Pay is available (e.g., `["US", "LT"]`)
`applePay.requiredBillingContactFields`	ApplePayContactField[]	Optional array of billing contact fields to request from the customer (see supported values below)
`applePay.requiredShippingContactFields`	ApplePayContactField[]	Optional array of shipping contact fields to request from the customer (see supported values below)

Supported values for ApplePayContactField:

Value	Description
`email`	Request the customer's email address
`name`	Request the customer's name
`phone`	Request the customer's phone number
`postalAddress`	Request the customer's postal address
`phoneticName`	Request the phonetic spelling of the name

Styles

You can customize various visual aspects of the checkout form using the styles property. Supported style options include:

Property	Type	Description
`borderRadius`	number	Border radius for input fields
`buttonColor`	string	Background color of the action button in hexadecimal
`buttonFontSize`	number	Font size of the action button text
`buttonTextColor`	string	Text color of the action button in hexadecimal
`fontFamily`	string	Font family for the checkout form from the list of supported fonts below
`fontSize`	number	Base font size for the checkout form
`textColor`	string	Text color for the checkout form in hexadecimal

Supported font families:

Roboto
Open Sans
Lato
Montserrat
Poppins
Inter
Noto Sans
Source Sans Pro
Raleway
Ubuntu
Work Sans
Nunito
Quicksand
Rubik
DM Sans

Layout

You can customize text labels and layout options in the checkout form using the layout property. Supported layout options include:

Property	Type	Description
`grouped`	boolean	Controls the visual layout of address fields (default: `true`). See details below
`actionButton.translationKey`	string	Change the text of the action button from the list below

Grouped Address Layout

The grouped property controls how billing and shipping address fields are visually rendered. It defaults to true.

When grouped is true (default):

A section title (e.g., "Billing Address") is displayed above the fields
Fields are visually merged into a single block with no gap between them
Only the outer corners of the block are rounded (using the configured borderRadius), giving the fields a unified card-like appearance
Fields use placeholders only, without separate labels
Related fields are placed side-by-side where applicable (e.g., first name / last name, city / zip code)

When grouped is false:

No section title is displayed
Each field is rendered individually with a 16px gap between them
Every field has full border radius on all corners
Each field displays both a label above the input and a placeholder inside it
All fields are rendered in full-width rows (no side-by-side layout)
Field order: first name, last name, street, city, country, state, zip code

Configuration:

const checkout = new OdusCheckout({
  // ... other configuration options
  appearance: {
    layout: {
      grouped: false, // Render address fields as individual separated inputs
    },
  },
});

Supported translation keys and their values:

Translation Key	Displayed Text
`pay`	PAY
`submit`	SUBMIT
`getPlan`	GET MY PLAN
`donate`	DONATE
`book`	BOOK NOW
`order`	ORDER NOW

Phone Number Field

The phone number field is a compound input that includes a country selector dropdown and a phone number input. The field automatically formats and validates phone numbers based on the selected country.

Visual Layout:

Country selector displays a flag icon for the selected country
Input field shows the phone number in international format (e.g., "+370 812 34 567")
Both components are styled to appear as a unified field

Behavior:

Phone numbers are formatted as you type according to the selected country's rules
Validation is country-specific using libphonenumber-js
Output format is E.164 (e.g., "+37081234567") for backend processing
Initial values in E.164 format are automatically parsed and formatted for display

Configuration:

const checkout = new OdusCheckout({
  // ... other configuration options
  appearance: {
    layout: {
      phoneNumber: {
        enabled: true, // Show/hide the phone number field
        label: 'Contact Number', // Optional custom label
        defaultCountry: 'LT', // Optional: default country (defaults to 'US')
        allowedCountries: ['US', 'GB', 'LT', 'DE'], // Optional: limit available countries
      },
    },
  },
  initialValues: {
    phoneNumber: '+37061234567', // Pre-fill with E.164 format
  },
});

Property	Type	Description
`phoneNumber.enabled`	boolean	Whether the phone number field is shown
`phoneNumber.label`	string	Custom label for the phone number field
`phoneNumber.defaultCountry`	string	Default selected country as ISO 3166-1 alpha-2 code (defaults to 'US')
`phoneNumber.allowedCountries`	string[]	Optional array of ISO 3166-1 alpha-2 country codes to show in the country selector

Note: If allowedCountries is not provided or is an empty array, all countries will be available in the country selector. The country selector displays flag emojis and localized country names, while the input shows the dial code as part of the formatted phone number.

Address Field Labels

Address fields (billing and shipping) support custom labels through the field configuration. If you provide a custom label in the field config, it will be used as the placeholder text. Otherwise, the translated placeholder from the built-in locale files is used automatically based on the current locale.

For example, the city field will display:

"City" in English (en)
"Stadt" in German (de)
"Ciudad" in Spanish (es)
"Ville" in French (fr)

This applies to all address fields: street, firstName, lastName, state, city, zipCode, and country.

The country field is rendered as a dropdown (select input) instead of a text input. You can configure which countries are available in the dropdown using the options property:

const checkout = new OdusCheckout({
  // ... other configuration options
  appearance: {
    layout: {
      billingFields: {
        country: {
          enabled: true,
          options: ['US', 'CA', 'GB', 'DE'], // Only show these countries
        },
      },
      shippingFields: {
        country: {
          enabled: true,
          options: ['US', 'CA'], // Different options for shipping
        },
      },
    },
  },
});

Property	Type	Description
`billingFields.country.enabled`	boolean	Whether the billing country field is shown
`billingFields.country.label`	string	Custom label for the billing country field
`billingFields.country.options`	string[]	Array of ISO 3166-1 alpha-2 country codes to show in the dropdown (e.g., `["US", "CA", "GB"]`)
`shippingFields.country.enabled`	boolean	Whether the shipping country field is shown
`shippingFields.country.label`	string	Custom label for the shipping country field
`shippingFields.country.options`	string[]	Array of ISO 3166-1 alpha-2 country codes to show in the dropdown (e.g., `["US", "CA", "GB"]`)

Note: If options is not provided or is an empty array, all countries will be available in the dropdown. The dropdown displays human-readable country names while submitting the ISO country code as the value.

The state field can also be rendered as a dropdown (select input) instead of a text input when you provide the options property. This is useful for limiting state/province selections to specific regions:

const checkout = new OdusCheckout({
  // ... other configuration options
  appearance: {
    layout: {
      billingFields: {
        state: {
          enabled: true,
          options: ['CA', 'NY', 'TX', 'FL'], // Only show these states
        },
      },
      shippingFields: {
        state: {
          enabled: true,
          options: ['CA', 'NY'], // Different options for shipping
        },
      },
    },
  },
});

Property	Type	Description
`billingFields.state.enabled`	boolean	Whether the billing state field is shown
`billingFields.state.label`	string	Custom label for the billing state field
`billingFields.state.options`	string[]	Array of state/province codes to show in the dropdown (e.g., `["CA", "NY"]`)
`shippingFields.state.enabled`	boolean	Whether the shipping state field is shown
`shippingFields.state.label`	string	Custom label for the shipping state field
`shippingFields.state.options`	string[]	Array of state/province codes to show in the dropdown (e.g., `["CA", "NY"]`)

Note: If options is not provided or is an empty array, the state field will be rendered as a regular text input. When options is provided, the field becomes a dropdown with the specified values.

Additional Payment Methods​

Styles​

Layout​

Grouped Address Layout​

Phone Number Field​

Address Field Labels​

Country Field Dropdown​

State Field Dropdown​

Additional Payment Methods

Styles

Layout

Grouped Address Layout

Phone Number Field

Address Field Labels

Country Field Dropdown

State Field Dropdown