@swell/react

Description

@swell/react is a wrapper around @swell/js that provides the hooks and other utils needed to quickly and easily build a storefront with Swell and React.

Getting Started

The only setup needed for @swell/react is to wrap your components within a Swell provider.

import { SwellContextProvider } from "@swell/react";

<SwellContextProvider storeKey={storeKey} store={store}>
	<App />
</SwellContextProvider>;

The hooks described below will now connect automatically to your store.

Hooks

useProduct

Fetches a product using the passed-in identifier, which can be either the product's ID or the product's slug.

Example

const { product } = useProduct("my-product");

API

const { product, activeVariant, loading, error } = useProduct(id, {
	expand,
	selectedOptions,
	planId,
	requestOptions,
});

The hook will listen to changes in the id and trigger a refetch, updating the loading boolean and the other returned values if necessary.

Alternatively you can pass an existing product as the first argument. This is useful when the product is fetched ahead of time (for example server-side) but you'd still like to make use of the activeVariant helpers.

import { getProduct } from "@swell/js";

const product = getProduct("my-product");

const { activeVariant } = useProduct(product, {
	selectedOptions: [{ optionId: "option-id", valueId: "value-id" }],
	planId: "plan-2",
});

Arguments:

• id (string): Identifier for the product. Can be either the product's slug or the product's id.
• options: (object, optional): Options for calculating the activeVariant and customizing the requests.
  • expand (object, optional): An array of the fields to expand. See Expandable fields for a list of the possible expand options.
  • selectedOptions (array, optional): The user's selected product options. Used to calculate the activeVariant.
  • planId: (string, optional): The selected subscription plan id (if any), used to calculate the activeVariant.
  • requestOptions (object, optional): Overwrites the client options for the current request. Parameters:
    • locale (string, optional): The requested product's locale.
    • currency (string, optional): The requested product's currency.
    • sessionToken (string, optional): The token from the session to be used.

Returns:

• product: The fetched product data.
• activeVariant: A variant that matches the passed-in user selections with resolved price data. See the @swell/js docs for more information.
• loading (boolean): true while fetching, false otherwise.
• error (string | null): The error message for request errors, if any.

useProductList

Returns a paginated list of the store's products, which can optionally be filtered by the passed-in attributes.

Example

const { products, loading, error } = useProductList({
  filters: {
    category: 'books'
    search: 'ring',
    author: 'J.R.R. Tolkien'
  },
})

In this example, the useProductList hook will attempt to retrieve a list of products that satisfies the following conditions (if any):

• The products must be inside of a category 'books'.
• Either the product title, the product slug or the product SKU must contain the term 'ring'.
• The product must have an 'author' attribute with the value of 'J.R.R. Tolkien'. Author is a custom product attribute specific to this store.

Changes to the filters will trigger a refetch and update the returned values accordingly.

API

const { products, loading, error } = getProductList(options);

Arguments:

• options (object, optional): Options for filtering and paginating the response. See the @swell/js docs for more information.

Returns:

• products: Paginated list of products
• loading (boolean)
• error (string | null)