SDKs & tools

ORBCART DOCUMENTATION

React checkout

Your Cart in, an Order out. One component for the last step of the purchase.

<Checkout> handles contact, addresses, shipping, payment, 3-D Secure, changed Quotes and slow payments. You supply the Cart and the confirmation page.

Add the checkout

CheckoutPage.tsx
import { useNavigate } from "react-router";
import type { CommerceCart } from "@orbcart/client";
import { Checkout } from "@orbcart/react";
import "@orbcart/react/styles.css";

export function CheckoutPage({ cart }: { cart: CommerceCart }) {
  const navigate = useNavigate();

  return (
    <Checkout
      cart={cart}
      locale="en-GB"
      onOrdered={(order) => navigate(`/orders/${order.number}`)}
    />
  );
}

Get cart from commerce.openCart(token) with the token from your session. Don't create a new Cart on every render.

A Cart for the whole storefront

Wrap your app in CartProvider. Any component can then add to the bag:

App.tsx
import { CartProvider, useShoppingCart } from "@orbcart/react";

<CartProvider commerce={commerce} token={savedToken} onCartChange={(cart) => saveToken(cart.token)}>
  <App />
</CartProvider>;

function AddToBag({ reference }: { reference: string }) {
  const { add } = useShoppingCart();
  return <button onClick={() => add(reference)}>Add to bag</button>;
}

add() creates the first Cart when needed and moves to a fresh one after a purchase, in every tab, and when a Cart has expired. onCartChange tells you when to save a new token. Other frameworks use the same logic through createShoppingCart(). The recipe Add to cart and a mini cart adds the header bag and keeps the token in a cookie.

One language for every component

Wrap your pages in OrbCartProvider once, and no component needs a locale of its own:

Shop.tsx
import { Money, OrbCartProvider } from "@orbcart/react";

<OrbCartProvider locale="de-CH">
  <Money money={current.estimate.totals.total} />
  <Checkout cart={cart} />
</OrbCartProvider>;

A component's own locale still wins. OrderPage speaks the order's language unless you pass one.

Props

PropExampleWhat it does
cartcommerce.openCart(token)The Cart to check out. Required.
locale"de-DE"Language, money format and the provider's field. Default: the provider's.
onOrdered(order) => navigate(...)Show your confirmation page.
start{ from: "quote", quote }Where the checkout starts. See below.
labels{ contact: { heading: "…" } }Override wording.
discountCodefalseHide the code field. Default: shown.
showEstimatefalseHide the estimate before the Quote. Default: shown.
lineImage(reference) => <img … />Your product images.
paymentHelp(method) => <TestCards … />Help next to the payment field.
deliveryAddressDhlDeliveryAddressYour own address fields, such as a pickup finder.
paymentOptions{ appearance: "inherit" }The provider's field in your theme, or styled in its own terms.
identity, onSignedInbetterAuthIdentity(…)Sign-in inside the checkout. Signed-in buyers →
buyer, signOut{ email }, <SignOutButton />For a buyer who is already signed in.
className"my-checkout"A class on the root, for theming.

Start after a redirect

Nothing to build. Back from PayPal, Klarna or iDEAL, or on the page an express review was handed to (/checkout?preparation=…), the checkout reads the page's address and resumes the purchase by itself. A normal reload needs nothing special either.

Pass start only to open a Quote you showed before:

<Checkout cart={cart} locale="en-GB" start={{ from: "quote", quote: quoteId }} />

Labels and languages

German and English labels are built in. de-DE, de-AT and de-CH select German; every other locale uses English labels with local money formatting. Override only what differs:

<Checkout
  cart={cart}
  locale="en-GB"
  labels={{
    contact: { heading: "How can we reach you?" },
    address: { countries: ["DE", "AT"] },
  }}
/>
  • Without countries, the country is a choice of your Channel's shipping countries. countries replaces that list: codes are named in the locale's language and sorted by name; pass { DE: "Deutschland" } instead to choose the names and the order yourself.
  • Messages about outcomes and payment method names come from describe(locale). Override them with words.
  • The order button's text is fixed by law and cannot be overridden.
  • defaultLabels(locale) gives you the built-in labels for your own markup.

Theme it

Use CSS variables and data-part selectors. Never rely on internal class names or HTML structure:

.my-checkout {
  --orbcart-color-text: #18212f;
  --orbcart-color-surface: #fff;
  --orbcart-color-action: #31476b;
  --orbcart-color-action-text: #fff;
  --orbcart-color-focus: #31476b;
  --orbcart-font-family: "Inter", sans-serif;
  --orbcart-radius: 0.5rem;
  --orbcart-control-height: 3.25rem;
}

.my-checkout [data-part="orbcart-checkout-summary"] {
  background: #f7f7f5;
}

More tokens: muted, border, error and attention colors, --orbcart-font-size and --orbcart-space. The card field from Adyen follows your light and dark theme automatically. For Stripe's field, pass paymentOptions={{ appearance: "inherit" }}: it reads the same tokens when the field appears. A field the buyer is typing in keeps its look through a switch to dark mode, so their card is never lost; the next field shows the new theme. If your fields float their labels, set --orbcart-field-labels: floating and Stripe's do too. Stripe sizes its field by a spacing unit rather than a height; where your fields are taller than Stripe's, set --orbcart-payment-spacing (such as 5px) to match them. packages/react/README.md lists every part and state attribute.

Build your own UI

Need different markup? useCheckout({ cart }) gives you the same state and actions as <Checkout>. Display its amounts; never calculate your own. Outside React, the checkout store it runs on does the same: A checkout without React.

Smaller building blocks are exported too: Cart, Line, OrderSummary, ShippingChoice, DiscountCode, Changes, Money, Address and ExpressCheckout for the bag. Cart, Line and OrderPage take lineImage and lineTitle, your product image and title for each Line, such as a link to the product's page. Those that hold state of their own have a matching hook, such as useLine() and useDiscountCode(). Pass the bag's steps on as they are: <Cart cart={bag.cart} onQuantityChange={bag.setQuantity} onRemove={bag.remove} />. A change the runtime refuses, such as more than is in stock, is said under its Line. A refusal of the whole cart, such as an order placed in another tab, is never said at a line: bag.cart becomes the cart as it now is, so show what fits it, such as the order once isSubmitted(bag.cart), as the demo's bag does. In a handler of your own, refusesTheCart(error.problem) from @orbcart/client tells the two apart. Totals shows the amounts of a quote, an estimate or an order the way the checkout does, for markup of your own; with compact it shows one amount, as a bag does, and notes what the total leaves out, as the estimate's excludes says:

import { Totals } from "@orbcart/react";

<Totals
  compact
  totals={current.estimate.totals}
  discounts={current.estimate.discounts}
  pricesIncludeTax={current.estimate.pricesIncludeTax}
  shipping={current.estimate.shipping}
  excludes={current.estimate.excludes}
/>;

<OrderPage order={order} /> shows a buyer their order after the purchase, from what commerce.order(token) read. The order page →

What the buyer sees when things are slow

  • 3-D Secure opens in a dialog above the page, also for wallets.
  • A payment that takes longer than 10 seconds shows a calm waiting panel instead of the form. It asks the buyer not to order again and turns into the confirmation once the provider answers.
  • A changed Quote shows what changed and asks again before charging.

Before going live

The kit is not a legally complete checkout yet. It links your legal texts at the order button and gives every buyer an order page; the withdrawal button is on the roadmap. Start in test mode.

Read Orders from your backend →

On this page