Version: 3.x

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.

tip

This guide is based on the alternative-checkout example from Front-Commerce.

Create the extension

Create a new extension extensions/custom-checkout in your project:

extensions/custom-checkout/index.ts
import { defineExtension } from "@front-commerce/core";

export default function customCheckout() {
  const basePath = `extensions/custom-checkout`;

  return defineExtension({
    meta: import.meta,
    name: "CustomCheckout",
    theme: `${basePath}/theme`,
  });
}

Create the new component and its enhancer

Create a new component that will combine both the address and shipping method functionality:

extensions/custom-checkout/theme/modules/Checkout/AddressAndShippingMethod.jsx
import Address from "theme/modules/Checkout/Address";
import ChooseShippingMethod from "theme/modules/Checkout/ChooseShippingMethod";
import {
  SetCheckoutShippingInformationDocument,
  SetCheckoutBillingAddressDocument,
} from "~/graphql/graphql";

const AddressAndShippingMethod = (props) => {
  return (
    <div>
      <Address {...props} />
      <ChooseShippingMethod {...props} />
    </div>
  );
};

export default EnhanceAddressAndShippingMethod({
  SetBillingAddressMutation: SetCheckoutBillingAddressDocument,
  SetShippingInformationMutation: SetCheckoutShippingInformationDocument,
})(AddressAndShippingMethod);

extensions/custom-checkout/theme/modules/Checkout/EnhanceAddressAndShippingMethod.jsx
import { compose } from "@front-commerce/compat/recompose";
import { FormattedMessage } from "react-intl";
import makeCommandDispatcher from "@front-commerce/compat/apollo/makeCommandDispatcher";
import CartQueryDocument from "~/graphql/graphql";
import { formatCheckoutAddressInput } from "theme/modules/Checkout/Address/formatCheckoutAddress";

export const FORM_TYPE_EXISTING_ADDRESS = "existing";
export const FORM_TYPE_NEW_ADDRESS = "new";

export default ({
  SetBillingAddressMutation,
  SetShippingInformationMutation,
}) =>
  compose(
    makeCommandDispatcher({
      setBillingAddress:
        (props) =>
        ({ address, email, onSuccess }) => {
          return {
            options: {
              mutation: SetBillingAddressMutation,
              variables: {
                email,
                billingAddress: formatCheckoutAddressInput(address),
              },
              update: (store, { data }) => {
                const response = data.setCheckoutBillingAddress;
                if (response.success) {
                  const cart = response.cart;

                  store.writeQuery({
                    query: CartQueryDocument,
                    data: { cart: cart },
                  });
                }
              },
            },
            callback: (result) => {
              if (result.status === "success") {
                onSuccess();
              }
            },
            messages: {
              error: (
                <FormattedMessage
                  id="modules.Checkout.Address.error"
                  defaultMessage="An error occured while recording your billing address. Please try again and if the problem persists contact us."
                />
              ),
            },
          };
        },
      onChooseShippingMethod: (props) => (method) => {
        const { method_code, carrier_code, additionalData } = method;
        return {
          options: {
            mutation: SetShippingInformationMutation,
            variables: {
              cartId: props.cartId,
              shippingAddress: formatCheckoutAddressInput(
                props.shippingAddress
                  ? props.shippingAddress
                  : { id: props.shippingAddressId }
              ),
              shippingMethod: {
                method_code,
                carrier_code,
                additionalData,
              },
            },
            update: (store, { data }) => {
              const response = data.setCheckoutShippingInformation;
              if (response.success) {
                const cart = response.cart;

                store.writeQuery({
                  query: CartQueryDocument,
                  data: { cart: cart },
                });
              }
            },
          },
          callback: (result) => {
            if (result.status === "success") {
              props.onChooseShippingMethod(method);
            }
          },
          messages: {
            error: (
              <FormattedMessage
                id="modules.Checkout.ShippingMethod.ChooseShippingMethod.error"
                defaultMessage="An error occured while recording your shipping information. Please try again and if the problem persists contact us."
              />
            ),
          },
        };
      },
    })
  );

Modify the steps definition

Modify your stepsDefinition.js to use the combined component:

extensions/custom-checkout/theme/pages/Checkout/stepsDefinition.jsx
import AddressAndShippingMethod from "theme/modules/Checkout/AddressAndShippingMethod";

const steps = [
  {
    renderProgressItem: (stepStatus, checkoutState) => {
      // Render combined progress item
    },
    renderStep: (props) => <AddressAndShippingMethod {...props} />,
    isValid: (checkoutState) => {
      // Combine validation from both address and shipping
      return (
        addressIsValid(checkoutState) && shippingMethodIsValid(checkoutState)
      );
    },
    isRelevant: () => true,
    isDisplayable: () => true,
  },
  // ... other steps (payment, review, etc.)
];

export default steps;

Register the extension

front-commerce.config.ts
// ... other imports
import customCheckout from "extensions/custom-checkout";

export default defineConfig({
  extensions: [themeChocolatine(), customCheckout()],
  // ... other config
});

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.

Change the checkout steps​

Example: Merging Address and Shipping Method Steps​

Changing the whole checkout system​

Change the checkout steps

Example: Merging Address and Shipping Method Steps

Changing the whole checkout system