# 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. tip You can visually tweak all appearance options in the interactive [Builder](https://docs.odus.com/docs/guides/checkout/drop-in/builder.md) and copy the generated configuration into your code. The `appearance` object has three root properties: | Property | Type | Description | | -------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | | `additionalPaymentMethods` | [AdditionalPaymentMethods](#additional-payment-methods) | Configures how alternative payment methods, such as PayPal and Apple Pay, are displayed in the checkout | | `styles` | [Styles](#styles) | Customize colors, fonts, and other visual aspects of the checkout form | | `layout` | [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](https://docs.odus.com/docs/guides/checkout/drop-in/getting-started.md#step-2-associate-a-payment) 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](https://docs.odus.com/docs/guides/checkout/drop-in/getting-started.md#step-2-associate-a-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 3166-1 alpha-2 country codes where PayPal is available (e.g., `["US", "LT"]`). Matched case-insensitively. Omit it, or pass an empty array, to offer PayPal everywhere | | `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 3166-1 alpha-2 country codes where Apple Pay is available (e.g., `["US", "LT"]`). Matched case-insensitively. Omit it, or pass an empty array, to offer Apple Pay everywhere | | [`applePay.requiredBillingContactFields`](https://developer.apple.com/documentation/applepayontheweb/applepaypaymentrequest/requiredbillingcontactfields) | ApplePayContactField\[] | Optional array of billing contact fields to request from the customer (see supported values below) | | [`applePay.requiredShippingContactFields`](https://developer.apple.com/documentation/applepayontheweb/applepaypaymentrequest/requiredshippingcontactfields) | ApplePayContactField\[] | Optional array of shipping contact fields to request from the customer (see supported values below) | Supported values for [`ApplePayContactField`](https://developer.apple.com/documentation/applepayontheweb/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`. ### Country Field Dropdown 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. ### State Field Dropdown The `state` field dynamically adapts based on the selected country: * **For the United States, Canada and Australia:** Renders as a **mandatory dropdown** populated with US states, Canadian provinces and territories, or Australian states and territories. Validation requires a selection before the form can be submitted. The submitted value is the subdivision code — `TX`, `ON`, `VIC` — not the full name. * **For all other countries:** Renders as an **optional text input**. The field can be left empty without blocking form submission. The field type updates automatically whenever the customer changes the country dropdown — no additional code is needed. #### Hiding the State Field for Specific Countries Use `hiddenForCountries` to hide the state field entirely when certain countries are selected. When hidden, the field does not appear in the form and validation is skipped — the form can be submitted without a state value. ``` const checkout = new OdusCheckout({ // ... other configuration options appearance: { layout: { billingFields: { country: { enabled: true }, state: { enabled: true, hiddenForCountries: ['LT', 'DE', 'FR'], // Hide state for these countries }, }, }, }, }); ``` ### Street Address Max Length Use `maxLength` to limit the number of characters a customer can type into the street address field. When the limit is reached, the input stops accepting characters and a localized validation message is displayed below the field. ``` const checkout = new OdusCheckout({ // ... other configuration options appearance: { layout: { billingFields: { street: { enabled: true, maxLength: 100, // Limit street address to 100 characters }, }, shippingFields: { street: { enabled: true, maxLength: 200, // Different limit for shipping }, }, }, }, }); ``` | Property | Type | Description | | --------------------------------- | ------ | --------------------------------------------------------------- | | `billingFields.street.maxLength` | number | Maximum characters allowed in the billing street address field | | `shippingFields.street.maxLength` | number | Maximum characters allowed in the shipping street address field | **Note:** If `maxLength` is not provided, the field accepts unlimited characters. The validation message is localized automatically based on the current locale.