Skip to main content
Version: next

Customize the checkout

This guide explains how to customize the checkout and reorganize checkout steps.

This page will guide you through checkout customization. For example, you may want to add a new step to the shipping/billing address, shipment methods, payment methods, and place order existing ones. It is also possible to completely rework the checkout process.

Change the checkout steps

The steps available in the checkout are defined in the file theme/pages/Checkout/stepsDefinition.js. Each step is defined by the following values:

{
// what should be displayed when showing the user the list of steps in a checkout
renderProgressItem: (stepStatus, checkoutState) => ReactElement,
// what should be displayed inside a step (mostly some forms relevant to your step)
renderStep: props => ReactElement,
// is the step finished (has the user defined all the data mandatory in your step ?)
isValid: checkoutState => Boolean
// is the step useful for this checkout state (should we display this step ?)
isRelevant: () => Boolean,
// unclear what the difference is between isRelevant/isDisplayable, should be cleaned in future releases
isDisplayable: () => Boolean
}

The checkoutState variable is all the data gathered from the user's input. It'll grow from step to step by adding addresses, shipping methods and payment methods. The best way to understand what has been set in a checkoutState is to look at the handlers set in EnhanceCheckout.js (setShippingAddress, setBillingAddress, etc.).

Example: Merging Address and Shipping Method Steps

Let's walk through a practical example of customizing the checkout by merging the address and shipping method steps into a single step. This is based on the alternative-checkout example from Front-Commerce.

You can now use your customized checkout steps.

Changing the whole checkout system

In some cases, you may not need to use the default steps available in Front-Commerce. However, it might still be interesting to reuse the mechanisms used by Front-Commerce's checkout. Indeed, any checkout will have this concept of steps. And since the steps definition is not coupled to our Enhancer, you can reuse it for your own project.

To do so, you will need to reuse the theme/modules/Checkout/withMultiStep enhancer file defined in theme/modules/Checkout/withMultiStep/.

This enhancer takes 4 arguments:

  • steps: the steps definition as explained in the first part
  • handlers: the methods that should update the checkoutState. The goal is to have predictable methods to update the checkoutState
  • initCheckoutState={}: the initial checkoutState when the user opens the Checkout
  • hasPersistantState=false: defines if the state should be stored in the url state of the browser. This allows the user to refresh the page without losing the whole page, but depending on the data you store inside your checkoutState, that might not be possible

We also advise you to look at theme/components/templates/MultiStep template that will let you reuse the props created by withMultiStep and display them in a React Component with a progress bar and the current step.