Package Products
Package products are products that consist of multiple sub-products, which may be discounted when bought together.
These sub-products may each have their own variants. Currently comments and configurations are not supported for package product items.
The usePackageProducts hook provides a robust API and state machine to handle everything from variants, loading, and adding to cart.
usePackageProducts
import { usePackageProduct } from '@jetshop/core/hooks/PackageProducts';
This component takes a single argument containing the following keys:
Arguments
The hook takes a single options object as an argument, with the following keys:
| Argument | Type | Required? | Description |
|---|---|---|---|
product |
Product |
true | The product entity returned from the API |
packageProductQuery |
DocumentNode | true | The query used to fetch the package details. |
priceQuery |
DocumentNode | false | The query used to fetch the package price. If not given will default to fetching both incVat and exVat fields |
packageProductQuery
For an example of this query, you can check the one used in Template trend here. The fragment it uses can be found here.
priceQuery
The default query can be found here. This will be used if you do not specify your own priceQuery.
Result
| Property | Type | Description | ||||||
|---|---|---|---|---|---|---|---|---|
status |
"loading" | "invalid" | "buyable" | "error" | "adding" | "added" | "fetching_price" |
The current status of the package. More detail below | ||||||
price |
{ price: [Price](https://schema-lfsgk0zv5.now.sh/price.doc.html), discountValue: [Price](https://schema-lfsgk0zv5.now.sh/price.doc.html) } |
An object containing the price of the package and the total package discount | ||||||
addPackageToCart |
(queries: AddMultipleToCartQueries) => void |
When called, this function will add the package to the cart | ||||||
packageProduct |
Product |
The full product, including package details. See note | ||||||
updatePackageItem |
(articleNumber: string, variantArticleNumber: string, valid: boolean) => void |
When called, this will set the variant of the given package item | ||||||
error |
{ fromState: string; messages: string[] } |
If there is an error when fetching the price or adding to cart, this object will contain the state in which the error occured and an array of error messges | ||||||
retry |
() => void |
This function resets the state to buyable, clearing any errors |
status
The current status of the package.
| Status | Description |
|---|---|
loading |
we are still fetching the data of your package product |
invalid |
The products in the package are in an invalid state. Either a variant has not been selected or an unbuyable variant has been selected |
buyable |
The package can be added to the cart |
error |
Something has gone wrong with adding the package to the cart |
adding |
The package is being added to the cart |
added |
The package has been successfully added to the cart |
fetching_price |
The price of the package is being fetched. The price may be different when different combinations of variants are selected. |
AddMultipleToCartQueries
The query and mutation used to add to and update the cart.
| Property | Description |
|---|---|
addMultipleToCartMutation |
The addMultipleToCartMutation used to add the package items to the cart |
cartQuery |
The query used in your store to fetch the cart details |
updatePackageItem
This function should be used in the case of a package item that has variants. As described above, it takes the package item's article number, the article number of the variant that has been selected, and a boolean indicating whether that variant is valid (buyable) or not.
The validity (buyable state) of the variant can be determined using the useProductVariants hook.
* Note on packageProduct
The usePackageProduct hook takes in a product, and returns a
packageProduct. It handles querying for the package details, and attaches
them to the product before returning it. It does this so that you do not have
to include all package-related fields in your product queries, which would
vastly increase the size of those queries.
In order to display the package data, you can use the packageProduct that is
returned from the hook. It will have a package field on it.
For this to work, make sure your product page gql query includes the isPackage field on the Product, as shown here in template trend.
This field determines whether the product is a package product, and if it is
true, the package details will be fetched.
usePackageProductItem
import { usePackageProductItem } from '@jetshop/core/hooks/PackageProducts';
This hook can be used when rendering each item in a package in order to handle updating the price and stockStatus of package item variants when they are selected in the UI. It will also update the package automatically whenever a package item variant is selected.
Arguments
The hook takes 2 arguments - the pacakge item, and the updatePackageItem
function returned from usePackageProduct.
| Argument | Type | Required? | Description |
|---|---|---|---|
item |
PackageItem |
true | The package item |
updatePackageItem |
UpdateItem |
true | This function is returned from usePackageItem |
options |
Options | false | Additional options |
Options
| Option | Type | Description |
|---|---|---|
preselectCheapest |
boolean | Will preselect the cheapest combination availiable for all variant articles in the package. |
Result
| Property | Type | Description |
|---|---|---|
price |
ProductConfigurationPrice |
The price and previousPrice of the package item or selected variant. Can be spread on to the Price component |
stockStatus |
StockStatusContainerRender |
The stock status of the item or selected variant |
variantHandler |
VariantHandler |
The result from useVariantHandler - see useVariantHandler docs |