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
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:
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:
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
| Prop | Example | What it does |
|---|---|---|
cart | commerce.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. |
discountCode | false | Hide the code field. Default: shown. |
showEstimate | false | Hide the estimate before the Quote. Default: shown. |
lineImage | (reference) => <img … /> | Your product images. |
paymentHelp | (method) => <TestCards … /> | Help next to the payment field. |
deliveryAddress | DhlDeliveryAddress | Your 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, onSignedIn | betterAuthIdentity(…) | 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.countriesreplaces that list: codes are named in thelocale'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 withwords. - 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.