React hooks for Commerce.js

A library of React hooks that can be used to integrate Commerce.js and interface with the Chec Dashboard.

Installation

Use your favourite package manager:

yarn add @chec/react-commercejs-hooks
# OR
npm install --save @chec/react-commercejs-hooks

Usage

Access to the Commerce.js SDK is provided with a context provider. This is used by the various hooks in this library to
access data from the Chec API. Ensure that you wrap any component that uses a Commerce.js hook in the CommerceContext
component:

import { CommerceContext } from '@chec/react-commercejs-hooks';

export default function MyComponent() {
  return (
    // Provide CommerceContext with your public key
    <CommerceContext publicKey="pk_123abc">
      <ProductList />
    </CommerceContext>
  );
}

The arguments for the Commerce.js SDK are supported as props on the CommerceContext component:

Prop
Purpose

publicKey
Your Chec public key, the first argument when using Commerce.js

debug
A boolean indicating whether the Commerce.js SDK should emit debug information to the console. The second argument of Commerce.js

options
An object with various options. This is the third argument of the Commerce.js SDK

You can use the Commerce.js SDK in any component that is a child of the CommerceContext component by using the
useCommerce hook:

import { useEffect } from 'react';
import { useCommerce } from '@chec/react-commercejs-hooks';

export default function ProductList() {
  const { commerce } = useCommerce();

  useEffect(() => {
    if (!commerce) {
      return;
    }

    commerce.products.list().then(products => {
      // ...
    })
  }, [commerce]);
}

Checkout hooks

This library provides many hooks for use with the checkout, but in order to use them, you must put components within a
checkout context by using the CheckoutProvider component. In the following example, a checkout is created from a
Commerce.js cart ID, passed in as a prop:

import { CheckoutProvider } from '@chec/react-commercejs-hooks/checkout';

export default function Checkout({ cartId }) {
  return (
    <CheckoutProvider id={cartId}>
      <LineItemSummary />
      <CustomerFields />
      <PaymentSummary />
      <PaymentForm />
    </CheckoutProvider>
  );
}

The following hooks are available for use within a checkout, and are all exported from
@chec/react-commercejs-hooks/checkout:

Hook
Purpose

useCheckout()
Provides the checkout (token) object that was fetched by Commerce.js (when available). The object structure of this is available here

useAllCountries()
Provides all countries that Commerce.js supports. See list all countries in the docs.

useAllSubdivisions()
Provides all subdivisions based on a country that Commerce.js supports. See list all subdivisions for a country in the docs.

useIsFree()
Checks whether a checkout has a zero payable balance. Returns a boolean, or null when the checkout is not available

useCheckQuantity()
Checks that a requested quantity is available for a line item ID. Variant and option IDs may also be provided if necessary. See check requested quantity in the docs.

useCheckVariant()
Checks that the provided variant ID and option ID is valid for the provided line item ID. See check variant in the docs.

useConditionals()
Provides the “conditionals” attribute from the checkout, indicating what conditional flags apply for the current checkout

useLineItems()
Provides the line items in the checkout

useLocationFromIp()
Provides geographic information about the user from their IP address. Returns the discovered location information, or null if the checkout is not available. See get buyer’s location from IP in the docs for more information.

useShippingCountries()
Provides the countries that are eligible for shipping based on the product selection in the checkout

useShippingOptions(country, region)
Provides the shipping options that can be selected for the given country (and region if provided) based on the product selection in the checkout

useShippingSubdivisions(countryCode)
Provides subdivisions of the given country code

useShippingSummary()
Provides detail of the chosen shipping method in the checkout

useTotals()
Provides the total cost of the checkout, and various subtotals within the checkout

useCapture()
Provides a callback that can be used to capture the checkout, with the given detail if provided

useCaptureWithStripe()
Extends the functionality of useCapture to provide integrated Stripe support, assuming that this hook is used within Elements context (from react-stripe-js)

useSetProductVariant()
Provides a callback that can be used to set a variant on a product within the checkout

useSetShippingOption()
Provides a callback that can be used to set the chosen shipping option for the checkout

useSetTaxZone()
Sets the tax zone for the checkout and updates the live object. See set tax zone in the docs.

useRegenerateCheckout()
Regenerate a checkout from the properties provided to the context. Can be useful to update the checkout when a cart changes in the same page.

Cart hooks

Cart hooks provided by this library leverage Vercel’s swr library: https://swr.vercel.app/. This provides efficient
request usage while maintaining data state across components and pages, all without having to wrap components in a React
context provider. Cart hooks must still be used within the CommerceContext though.
The following hooks are available for use for carts, and are all exported from @chec/react-commercejs-hooks/cart. The
arguments for most cart update methods are the same as Commerce.js functions, which are detailed in the
docs:

Hook
Purpose

useCart()
Provides the active cart, or a cart for a specific ID if specified. The object structure of this is available here

useActiveCartId()
Provides the ID of the active cart – tracked in the users browser

useAddToCart()
Provides a callback that can be used to add a product to the cart. Takes a product ID and an optional quantity of items to add

useUpdateCart()
Provides a callback that can be used to update line items in the cart. Takes the same arguments as commerce.cart.update in Commerce.js

useRemoveFromCart()
Provides a callback that can be used to remove a given line item (by ID) from the cart

useEmptyCart()
Provides a callback that can be used to empty the cart

useCreateNewCart()
Provides a callback that can be used to replace the current cart with a new empty cart