Documentation

Customize the style of Checkout

Elevate, May 20-22-2025, Miami Beach, Florida

Customize and style your checkout experience with Checkout.

Checkout lets you customize the font family and colors of your checkout experience. You can do this by passing the styles configuration property with the checkoutFlow or paymentFlow methods when initializing Checkout.

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 example sets the font family to Helvetica.

Set the font family to Helvetica using the 'checkoutFlow' methodjavascript
import { checkoutFlow } from '@commercetools/checkout-browser-sdk';

checkoutFlow({
  projectKey: '{projectKey}',
  region: '{region}',
  sessionId: '{sessionId}',
  styles: {
    '--font-family': 'Helvetica',
  },
});

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.
VariableDescription
--buttonSets the background color of the primary button.
--button-textSets the text color of the primary button.
--button-disabledSets the background color of the primary button when it's not enabled.
--button-disabled-textSets the text color of buttons when they are not enabled.
--input-field-focusSets the text color in an input field when clicked.
--checkboxSets the color of a selected checkbox.
--radioSets the color of a selected radio button.

The following example sets the color of checkboxes and radio buttons to red.

Set the color of checkboxes and radio buttons to red using the 'checkoutFlow' methodjavascript
import { checkoutFlow } from '@commercetools/checkout-browser-sdk';

checkoutFlow({
  projectKey: '{projectKey}',
  region: '{region}',
  sessionId: '{sessionId}',
  styles: {
    '--checkbox': '#ff0000',
    '--radio': '#ff0000',
  },
});

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.