Skip to Content
Build a shop

ORBCOMMERCE DOCUMENTATION

A checkout with a page per step

Contact, delivery and payment each on their own address, with the browser's back button, a reload and the provider's return all landing on the right step.

Give each step of the checkout its own page: /checkout/contact, /checkout/delivery, /checkout/payment. The Cart says which step a buyer may open, your router shows it.

You need a React storefront with a router and a Cart, such as the one from Add to cart. React checkout explains steps on one page first.

1. One route, one component

Every step's page renders the same <Checkout> with the same children. step says which step this page is, and onStepChange asks for another one. With React Router, as one route /checkout/:step:

CheckoutStepPage.tsx
import { useNavigate, useParams } from "react-router";
import type { CommerceCart } from "@orbcart/client";
import {
  Checkout,
  CheckoutAddress,
  CheckoutContact,
  CheckoutExtensions,
  CheckoutPayment,
  CheckoutShipping,
  CheckoutStep,
  CheckoutSummary,
} from "@orbcart/react";
import "@orbcart/react/styles.css";

export function CheckoutStepPage({ cart }: { cart: CommerceCart }) {
  const { step = "contact" } = useParams();
  const navigate = useNavigate();

  return (
    <Checkout
      cart={cart}
      locale="en-GB"
      step={step}
      onStepChange={(name) => navigate(`/checkout/${name}`)}
      onOrdered={(order) => navigate(`/orders/${order.number}`)}
    >
      <CheckoutStep name="contact" heading="Contact">
        <CheckoutContact />
      </CheckoutStep>
      <CheckoutStep name="delivery" heading="Delivery">
        <CheckoutShipping part="way" />
        <CheckoutAddress />
        <CheckoutShipping part="methods" />
        <CheckoutExtensions />
      </CheckoutStep>
      <CheckoutStep name="payment" heading="Payment">
        <CheckoutPayment />
      </CheckoutStep>
      <CheckoutSummary />
    </Checkout>
  );
}

A name is what stands in the address, so keep it short and stable. The steps that are not this page's show as their heading, with one line of what the buyer gave once they are complete.

2. When the checkout asks for another step

onStepChange(name) is called in three cases. Navigate to that step's page in each:

The buyername is
pressed "Continue" and the step lacks nothingthe first step that still lacks something
pressed "Change" on a complete step, or a notice's buttonthat step
opened a page the Cart does not allow yetthe first step that still lacks something

The last case covers a bookmarked /checkout/payment with an empty contact. The check runs when the buyer enters a page. What happens on a page never sends them away from it: a payment page whose Cart lost something it needs, such as a shipping method that is no longer offered, says what is missing with a button to the step that asks it.

Navigate to the step's own address, without the query the last page had. After a payment at the provider the buyer returns with ?payment=…; a next page that kept it would resume that payment once more.

3. What survives the way between pages

  • The Cart. Each step saves on "Continue". The next page reads it again.
  • What the buyer typed and did not save, in the tab's sessionStorage for that Cart: contact, addresses and answers to the fields you ask. It is there after the back button and after a reload, and gone once the Cart is ordered.
  • What the checkout last said. A field the runtime refused at the order is marked on the page its notice leads to, and the reason of a declined payment is still said on the payment page.
  • Not the card. A provider's field lives on its page, so the buyer types the card on the payment page and orders there. This is why there is no review page after the payment.

What the buyer sees

MomentThe page shows
They press "Continue"The next step's page, with its heading focused.
They press the browser's back buttonThe step before, with what they gave, ready to change.
They reloadThe same step, with what they typed.
They open the payment page too earlyThe first step that still lacks something.
A payment method needs a phone numberA notice on the payment page with a button to the contact page.
The runtime refuses the address at the orderA notice on the payment page with a button to the delivery page, the field marked there.
They come back from the provider without an orderThe payment page, with the reason.
They come back with a filled CartThe payment page: one click from the order.

Next

On this page