UseProductVariantContext hook

import {
  useProductContext,
  useProductVariantContext,
  useProductPriceContext,
  useProductStockContext,
} from 'sana/product';

const productVariantContext = useProductVariantContext();

This hook can be used in a content element on the product details page. Content elements can programmatically change the selected product variant displayed on the page.

The useProductVariantContext hook provides an API for selecting a different product variant. Calling setVariantId produces the same result as the customer selecting that variant through the built-in variant selector: price, stock, media, and other variant-dependent data are updated accordingly.

To read the currently selected variant, use useProductContext and read its variantId property. It updates automatically when the variant changes via setVariantId or the built-in variant selector.

Note: If both a custom variant selector and the built-in variant dropdown are present on the same page, the built-in dropdown UI does not synchronize with setVariantId. This is not an issue when the custom selector replaces the default one.

This hook returns the object with data or null in case:

• the hook is not being used on the product details page;
• the product data is not loaded yet;
• the product does not have variants;
• the product has no variant component groups;
• product variants are presented in the matrix display mode.

Unlike useProductCommentContext, this hook does not return null for configurable or non-orderable products when the conditions above are met. Add to cart may still be unavailable due to other ability or order box restrictions.

Visual Designer

Variant selection does not work in Visual Designer preview (setVariantId has no effect). Test on a live product details page.

Variant ID

variantId must be a valid variant identifier for the current product (an opaque ERP/Sana variant identifier string). Invalid values are ignored without an error.

There is no public API to enumerate all variant IDs. Use your own data source (for example, an ERP integration, a GraphQL add-on API, or product media with variantId) to build variant selection UI.

Data

The data contains the following property:

Property	Type	Description
setVariantId	(variantId: string) => void	Selects a different product variant on the product details page. If variantId does not match any valid variant combination, the call is ignored.

After setVariantId is called, useProductContext reflects the updated variant. Related hooks such as useProductPriceContext and useProductStockContext are updated as well.

Quantity, comment, and custom field values entered via useProductQuantityContext, useProductCommentContext, and useProductFieldContext are not reset when the variant changes.

When selecting a variant whose calculated data (price, stock) has not been loaded yet, the page may briefly show a loading state while variant data is fetched. This is the same behavior as when using the built-in variant selector.

Example:

import {
  useProductContext,
  useProductVariantContext,
  useProductPriceContext,
  useProductStockContext,
} from 'sana/product';

const CustomVariantSelector = () => {
  const product = useProductContext();
  const productVariantContext = useProductVariantContext();
  const productPrice = useProductPriceContext();
  const stockInfo = useProductStockContext();

  if (!productVariantContext)
    return null;

  const { setVariantId } = productVariantContext;

  return (
    <div>
      <div>Current variant: {product?.variantId ?? '(none)'}</div>
      <div>Price: {productPrice?.price ?? '(n/a)'}</div>
      <div>Stock level: {stockInfo?.stockLevel ?? '(n/a)'}</div>
      <button type="button" onClick={() => setVariantId('VARIANT_ID')}>
        Select variant
      </button>
    </div>
  );
};

Related hooks

Hook	Purpose
useProductContext	Read product data, including the current variantId
useProductPriceContext	Read price for the currently selected variant
useProductStockContext	Read stock for the currently selected variant