Checkout steps React component for Tailwind CSS v4

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

Checkout steps is part of Pro, with 298 more Pro items: $8 a month or $150 once. 14-day refund before you download any Pro item. See plans

Usage

Import CheckoutSteps from @/components/ui/checkout-steps.

import { CheckoutSteps, type DeliveryMethod, type PaymentMethod } from "@/components/ui/checkout-steps"
import type { CartItem } from "@/components/ui/cart-drawer"
import { RO_VAT_RATE } from "@/lib/commerce"
import { cityOptions, countyOptions } from "@/lib/ro-locations"

const items: CartItem[] = [
  { id: "case", title: "iPhone 14 case, silicone, Midnight", price: 79.9, quantity: 2, image: "/demo/phone.jpg" },
  { id: "stand", title: "Aluminum laptop stand", price: 149, quantity: 1, image: "/demo/laptop.jpg" },
]

const delivery: DeliveryMethod[] = [
  { id: "fan", label: "Fan Courier", price: 19.99, eta: "1-2 business days", type: "courier" },
  { id: "pickup", label: "Pick up in Cluj-Napoca", price: 0, type: "pickup" },
]

const payment: PaymentMethod[] = [
  { id: "card", label: "Card" },
  { id: "cash", label: "Cash on delivery", fee: 4.99 },
]

export function Checkout() {
  return (
    <CheckoutSteps
      items={items}
      regions={countyOptions()}
      getCities={(county) => cityOptions(county)}
      deliveryMethods={delivery}
      paymentMethods={payment}
      freeShippingThreshold={250}
      taxRate={RO_VAT_RATE}
      tone="brand"
      onPlaceOrder={(value, totals) =>
        fetch("/api/orders", { method: "POST", body: JSON.stringify({ value, total: totals.total }) })
      }
      successContent={<p>Order #1042 is placed.</p>}
      labels={{
        review: "Confirm",
        placeOrder: (total) => `Pay ${total}`,
      }}
    />
  )
}

Props

• items*
  CartItem[]

  The cart lines (CartItem from cart-drawer): id, title, price, quantity, compareAtPrice, taxRate, image, variant. Unavailable lines and quantity 0 are left out; an empty list shows the empty state.

• value
  CheckoutValue

  Controlled checkout data: email, addressId, address (CheckoutAddress), invoice (CheckoutInvoice), deliveryMethod, lockerId, paymentMethod, notes, acceptTerms, coupons (AppliedCoupon[]). Pair it with onValueChange.

• defaultValuedefault "{}"
  CheckoutValue

  The starting data while uncontrolled (a returning buyer's email, a remembered method).

• onValueChange
  (value: CheckoutValue) => void

  Called with the whole value on every change.

• defaultStepdefault "address"
  "address" | "delivery" | "payment" | "review"

  The step it opens on while uncontrolled; the steps before it count as done.

• step
  CheckoutStepId

  The controlled step; pair it with onStepChange.

• onStepChange
  (step: CheckoutStepId) => void

  Called when the step changes (Continue, Back, Edit links, the stepper).

• stepsdefault "["address", "delivery", "payment", "review"]"
  CheckoutStepId[]

  The steps in order, e.g. ["payment", "review"] for a digital product. A step whose data is missing (delivery without deliveryMethods) is skipped with a warning in development.

• savedAddressesdefault "[]"
  CheckoutAddress[]

  Address cards to pick from, plus New address. The first one is chosen at the start; one missing a required field shows Complete the address and opens the form.

• regions
  { value: string; label: string; description?: string }[]

  The County select (countyOptions() from ro-locations); without it the county is a text field.

• getCities
  (region: string) => (CheckoutCity[] | Promise<CheckoutCity[]>)

  The City combobox for the chosen county ({ value, label, description, keywords }[]), sync or async (cityOptions(county) from ro-locations); without it a text field. Typed names outside the list are kept.

• deliveryMethods
  DeliveryMethod[]

  Required when the delivery step is used: { id, label, description, price, eta, type: courier | locker | pickup, icon, logo, freeFrom, disabled }. Prices turn to Free in place once the threshold or a coupon makes them free.

• lockers
  CheckoutLocker[] or (methodId: string) => Promise<CheckoutLocker[]>

  The pickup points of a locker method ({ id, label, address, distance, hours }), or a loader called per method (skeleton rows while it runs). A locker method then needs a chosen point.

• paymentMethods
  PaymentMethod[]

  Required when the payment step is used: { id, label, description, icon, logos, fee, minTotal, disabled, details }. fee joins the summary and the total; below minTotal the card is disabled with Available from; details (a card form slot, the IBAN) unfold under the cards while chosen.

• invoicedefault true
  boolean

  Shows the Individual / Company switch and the company fields (name, CUI checked with the ANAF key, trade register no.).

• requireTermsdefault true
  boolean

  Shows the terms checkbox in the review step and requires it before the order is placed.

• termsLabeldefault "labels.terms"
  ReactNode

  The terms checkbox label, with links to the terms and privacy pages.

• showCoupondefault true
  boolean

  The promo code field in the summary.

• couponProps
  Partial<CouponInputProps>

  Passed to the CouponInput: the coupons catalogue, onApply for a server check, labels.

• freeShippingThresholddefault 0
  number

  Courier and locker delivery is free from this much (items after coupons); a method's freeFrom wins. 0: no offer.

• taxRatedefault 0
  number

  The VAT rate as a fraction (0.21); 0 hides the VAT row. Lines can carry their own rate.

• pricesIncludeTaxdefault true
  boolean

  Prices include VAT (Romanian B2C); false adds VAT on top as its own row.

• summarydefault "aside"
  "aside" | "collapsible" | "none"

  aside: a sticky summary column once the checkout itself is 896px wide (a container query), a Show summary bar when narrower; collapsible: the bar at every width; none: no summary.

• stepperdefault "horizontal"
  "horizontal" | "progress"

  The form-wizard header from 768px: numbered steps, or a progress bar with the step title. Phones always show the compact progress.

• fullScreenOnMobiledefault true
  boolean

  Below 768px each step fills the container: the summary bar and step count on top, a sticky footer with the total and Continue above the home indicator.

• onPlaceOrder
  (value: CheckoutValue, totals: CartTotals) => (void | Promise<unknown>)

  Places the order after the review step validates; totals.total includes the payment fee. A promise shows the button loading; a resolve turns it into a check, then successContent; a rejection shows an alert with its message in the review step.

• successContent
  ReactNode

  Replaces the wizard once the order is placed (order number, next steps).

• tonedefault "neutral"
  "neutral" | "brand" | "success" | "warning" | "danger" | "info"

  Continue, Place order and the stepper's active marker.

• colordefault ""
  string

  Any CSS color for the same parts; replaces the tone.

• sizedefault "md"
  "sm" | "md"

  Fields, cards, the stepper and the buttons: sm for a narrow column, md for the page.

• radiusdefault "md"
  "none" | "sm" | "md" | "lg" | "full"

  The corners of Back, Continue and Place order.

• countrydefault "RO"
  string

  RO checks the postal code (6 digits) and the CUI control key and starts the phone at +40; other codes relax those checks.

• currencydefault "RON"
  string

  ISO 4217 code for every amount.

• localedefault ""
  string

  Locale for prices and numbers; empty uses the UIProvider's, then the browser's.

• labels
  Partial<CheckoutStepsLabels>

  Every string, English by default (DEFAULT_CHECKOUT_STEPS_LABELS): the step titles address "Delivery details", delivery "Shipping", payment "Payment", review "Review"; continue, back, placeOrder(total) "Place order · RON 1,284.90", placed, stepOf(i, n), edit, newAddress, incompleteAddress, contact, the field labels (name, phone, email, county, city, street, details, postalCode, companyName, cui, regCom) and placeholders (emailPlaceholder, countyPlaceholder, cityPlaceholder, cuiPlaceholder, regComPlaceholder), invoiceTitle, person, company, locker, lockerSearch, free, fee(amount), minTotal(amount), paymentFee(method), notes, terms, summary, showSummary(total), hideSummary, the summary rows (subtotal, shipping, total...) and the errors (required, invalidEmail, invalidPhone, invalidCui, invalidPostalCode, acceptTerms, chooseDelivery, chooseLocker, choosePayment).

• classNames
  Partial<Record<"layout" | "wizard" | "summary" | "summaryBar" | "address" | "delivery" | "payment" | "review" | "placeOrder", string>>

  Extra classes for the inner parts.

• className
  string

  Extra classes for the root, merged last.

Parts

FAQ

Used in

More React commerce components