This is the early access documentation preview for Custom Views. This documentation might not be in sync with our official documentation.

Customize the style of Checkout

Customize and style your checkout experience with commercetools Checkout.

commercetools Checkout lets you customize the font family and colors of your checkout experience. This is possible by adding the optional styles object in the checkoutConfig object during the checkout initialization.

commercetools Checkout supports only the variables mentioned on this page. Any other variable declared will be ignored.

Customize the font family

To customize the font family, use the --font-family variable within the styles object. All system fonts are accepted, and the selected font will be used across checkout. The following examples set the font family to Helvetica.

Set the font family to Helvetica using the Browser SDKJavaScript

import { ctc } from '@commercetools/checkout-browser-sdk';

ctc('init', {
  checkoutConfig: {
    projectKey: '{projectKey}',
    applicationKey: '{applicationKey}',
    styles: {
      '--font-family': 'Helvetica',
    },
  },
});

Set the font family to Helvetica using a WebView componentJavaScript

injectedJavaScript={`
   window.commercetoolsCheckoutData =  {
     projectKey: '{projectKey}',
     applicationKey: '{applicationKey}',
     cartId: '{cartId}',
     host: 'https://app.checkout.{region}.commercetools.com',
     accessToken: '{accessToken}',
     locale: '{locale}',
     styles: {
      '--font-family': 'Helvetica',
     },
   }
   window.initCommercetoolsCheckout();
   window.addEventListener('message', function (messageEvent) {
     if (origin === '{commercetoolsCheckoutHost}') {
       window.ReactNativeWebView.postMessage(JSON.stringify(messageEvent.data));
     }
   });
 `}

Customize colors

To customize the color of available buttons and their associated font, use the respective variables within the styles object.

Using --button to set the background color of the primary button also affects the appearance of the secondary button and the low-opacity button. The secondary button will use the same color for its display text with a transparent background. The low-opacity button will use the same background color, but has transparency mixed in.

Variable	Description
`--button`	Sets the background color of the primary button.
`--button-text`	Sets the text color of the primary button.
`--button-disabled`	Sets the background color of the primary button when it's not enabled.
`--button-disabled-text`	Sets the text color of buttons when they are not enabled.
`--input-field-focus`	Sets the text color in an input field when clicked.
`--checkbox`	Sets the color of a selected checkbox.
`--radio`	Sets the color of a selected radio button.

The following examples set the color of checkboxes and radio buttons to red.

Set the color of checkboxes and radio buttons to red using the Browser SDKJavaScript

import { ctc } from '@commercetools/checkout-browser-sdk';

ctc('init', {
  checkoutConfig: {
    projectKey: '{projectKey}',
    applicationKey: '{applicationKey}',
    styles: {
      '--checkbox': '#ff0000',
      '--radio': '#ff0000',
    },
  },
});

Set the color of checkboxes and radio buttons to red using a WebView componentJavaScript

injectedJavaScript={`
  window.commercetoolsCheckoutData =  {
    projectKey: '{projectKey}',
    applicationKey: '{applicationKey}',
    cartId: '{cartId}',
    host: 'https://app.checkout.{region}.commercetools.com',
    accessToken: '{accessToken}',
    locale: '{locale}',
    styles: {
    '--checkbox': '#ff0000',
    '--radio': '#ff0000',
    },
  }
  window.initCommercetoolsCheckout();
  window.addEventListener('message', function (messageEvent) {
    if (origin === '{commercetoolsCheckoutHost}') {
      window.ReactNativeWebView.postMessage(JSON.stringify(messageEvent.data));
    }
  });
`}

Best practices for accessibility

To be inclusive of individuals with visual limitations and ensure optimal accessibility, we advise to use the right choice of colors with appropriate contrast. Therefore, it is recommended to comply with accessibility standards in terms of color and contrast, and choose the best combination that matches your branding to increase readability. To facilitate this, tools such as color contrast checkers help you evaluate the contrast ratio between two colors.

Web Content Accessibility Guidelines (WCAG) 2.1 recommends a minimum contrast ratio of 4.5:1 for information-bearing elements. However, a contrast ratio of 3:1 is made for exceptions such as large texts (14pt bold+ or 18pt regular+), UI controls (including states, excluding not enabled state), and graphical objects.