Skip to main content
Version: 2.x

Add a custom checkout step

Checkout is one of the most complex parts of any e-commerce website. If you use a relatively standard checkout, you hopefully won't have to change anything more than a few components to adapt them to your look and feel. However, if you add a custom step, you'll need to change a few things.

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.

Add a new step to the checkout​

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.).

Thus, if we want to add our own step, we need to duplicate the stepsDefinitions.js and add our step following the above documentation.

Add a comment step to your Checkout​

In order to illustrate this concept, we will add a new step which will enable the user to leave a comment with their command.

WIP
We didn't add the example yet. If you need it right away, please contact us. We will make sure to answer you in a timely manner.

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 node_modules/front-commerce/src/web/theme/modules/Checkout/withMultiStep/.

This enhance 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.