Skip to main content

Checkout

Multi-step checkout flow management component with step-specific state management and navigation.

Purpose​

This library provides a headless multi-step checkout flow system that manages step navigation, state management, and step-specific data storage. It's designed as a context provider that enables complete UI customization while handling the complexity of multi-step form flows, step validation, and step transitions.

Features​

  • Multi-step checkout flow management
  • Step-specific data storage and retrieval
  • Automatic step navigation controls
  • Step validation callbacks
  • Transition state management
  • Automatic data attributes for step elements

Installation​

npm install @haus-storefront-react/checkout

Note: This is not a public package. Contact the Haus Tech Team for access.

API Reference​

CheckoutProvider​

Main checkout context provider that manages multi-step checkout flow state and provides context to child components.

Props

PropTypeRequiredDefaultDescription
childrenReact.ReactNodeYes-Child components that will have access to checkout context

useCheckoutContext​

Hook to access checkout context and operations. Provides overloads for accessing full context or step-specific context.

Parameters

When called without parameters:

No parameters - Returns full checkout context

When called with step parameter:

ParameterTypeRequiredDescription
stepTStep extends keyof TDataYesThe step index to get step-specific context

Returns

Full Context (no step parameter):

Return ValueTypeDescription
currentStepnumberCurrent active step index
finishedStepsnumber[]Array of completed step indices
dataTDataAll step data indexed by step number
canGoToNextStepbooleanWhether navigation to next step is possible
canGoToPreviousStepbooleanWhether navigation to previous step is possible
stepRefsreadonly React.RefObject<HTMLElement>[]Array of refs for each step element
nextStep(props?: StepFunctionProps) => voidFunction to navigate to next step
previousStep(props?: StepFunctionProps) => voidFunction to navigate to previous step
gotoStep(step: number, props?: StepFunctionProps) => voidFunction to navigate to specific step
setCurrentStepDispatch<SetStateAction<number>>Function to directly set current step
setDataDispatch<SetStateAction<TData>>Function to set all step data
setDataForStep(data: CheckoutDataType, step: number) => voidFunction to set data for a specific step
setStepRef(el: HTMLElement, stepIndex: number) => voidFunction to register a step element ref

Step-Specific Context (with step parameter):

Returns the same properties as full context, but with:

  • data - The specific step's data (TData[TStep])
  • ref - The ref for the specific step (RefObject<unknown>)

Throws

Throws an error if used outside of CheckoutProvider.

Data Attributes

The component automatically adds data attributes to step elements when refs are registered via setStepRef:

  • data-step - Step index
  • data-finished - Whether step is finished (boolean string)
  • data-current - Whether step is current (boolean string)
  • data-total-steps - Total number of steps
  • data-can-go-next - Whether can proceed to next step (boolean string)
  • data-can-go-previous - Whether can go back (boolean string)
  • data-step-data - JSON string of step data
  • data-is-transitioning-in - Whether step is transitioning in (boolean string)
  • data-is-transitioning-out - Whether step is transitioning out (boolean string)

StepFunctionProps​

Configuration object for step navigation functions (nextStep, previousStep, gotoStep).

Properties

PropertyTypeRequiredDescription
onClick() => Promise<void> | voidNoCallback executed before step change attempt
onStepChange() => Promise<void> | voidNoCallback executed after successful step change
onFailed() => Promise<void> | voidNoCallback executed when step change fails

Basic Usage​

Simple Multi-Step Flow​

import {
  CheckoutProvider,
  useCheckoutContext,
} from '@haus-storefront-react/checkout'

function CheckoutApp() {
  return (
    <CheckoutProvider>
      <CheckoutFlow />
    </CheckoutProvider>
  )
}

function CheckoutFlow() {
  const {
    currentStep,
    nextStep,
    previousStep,
    canGoToNextStep,
    canGoToPreviousStep,
  } = useCheckoutContext()

  return (
    <div>
      <div>Current Step: {currentStep}</div>

      <button onClick={() => previousStep()} disabled={!canGoToPreviousStep}>
        Previous
      </button>

      <button onClick={() => nextStep()} disabled={!canGoToNextStep}>
        Next
      </button>
    </div>
  )
}

Step-Specific Context​

import { useCheckoutContext } from '@haus-storefront-react/checkout'

function CustomerStep() {
  const { data, setDataForStep, setStepRef } = useCheckoutContext(0)

  const handleSave = () => {
    setDataForStep({ name: 'John Doe', email: 'john@example.com' }, 0)
  }

  return (
    <div ref={(el: HTMLDivElement) => el && setStepRef(el, 0)}>
      <h2>Customer Information</h2>
      <input defaultValue={(data as { name?: string })?.name} />
      <input defaultValue={(data as { email?: string })?.email} />
      <button onClick={handleSave}>Save</button>
    </div>
  )
}

Advanced Usage​

Complete Multi-Step Checkout​

import {
  CheckoutProvider,
  useCheckoutContext,
} from '@haus-storefront-react/checkout'

function CompleteCheckout() {
  return (
    <CheckoutProvider>
      <CheckoutSteps />
    </CheckoutProvider>
  )
}

function CheckoutSteps() {
  const {
    currentStep,
    nextStep,
    previousStep,
    canGoToNextStep,
    canGoToPreviousStep,
  } = useCheckoutContext()

  return (
    <div>
      <StepIndicator currentStep={currentStep} />
      <div>
        {currentStep === 0 && <CustomerStep />}
        {currentStep === 1 && <AddressStep />}
        {currentStep === 2 && <PaymentStep />}
        {currentStep === 3 && <ReviewStep />}
      </div>
      <NavigationButtons
        onNext={nextStep}
        onPrevious={previousStep}
        canGoNext={canGoToNextStep}
        canGoPrevious={canGoToPreviousStep}
      />
    </div>
  )
}

function CustomerStep() {
  const { data, setDataForStep, setStepRef } = useCheckoutContext(0)

  return (
    <div ref={(el: HTMLDivElement) => el && setStepRef(el, 0)}>
      <h2>Customer Information</h2>
      <input
        defaultValue={(data as { name?: string })?.name}
        onChange={(e) => setDataForStep({ name: e.target.value }, 0)}
      />
    </div>
  )
}

Conditional Step Navigation​

import { useCheckoutContext } from '@haus-storefront-react/checkout'

function ConditionalNavigation() {
  const { gotoStep, currentStep, nextStep } = useCheckoutContext()

  const handleSkip = () => {
    gotoStep(3, {
      onClick: async () => {
        console.log('Skipping steps 1 and 2')
      },
      onStepChange: async () => {
        console.log('Jumped to step 3')
      },
    })
  }

  return (
    <div>
      {currentStep === 0 && (
        <button onClick={handleSkip}>Skip Optional Steps</button>
      )}
      <button onClick={() => nextStep()}>Continue Normally</button>
    </div>
  )
}

Made with ❤️ by Haus Tech Team