Choose a version:

useOptimisticVariant

The useOptimisticVariant takes an existing product variant, processes a pending navigation to another product variant, and returns the data of the destination variant. This makes switching product options immediate.

Anchor to useOptimisticVariant
useOptimisticVariant(
selectedVariant
,
variants
)

Anchor to useOptimisticVariant-parametersParameters

Anchor to selectedVariant selectedVariant SelectedVariant required: The selectedVariant field queried with variantBySelectedOptions.
Anchor to variants variants Variants required: The available product variants for the product. This can be an array of variants, a promise that resolves to an array of variants, or an object with a product key that contains the variants.

Anchor to useOptimisticVariant-returnsReturns

A new product object where the selectedVariant property is set to the variant that matches the current URL search params. If no variant is found, the original product object is returned. The isOptimistic property is set to true if the selectedVariant has been optimistically changed.

OptimisticVariant

T & {
  isOptimistic?: boolean;
}

OptimisticVariantInput

__typename
```
'ProductVariant'
```
availableForSale
Indicates if the product variant is available for sale.
```
boolean
```
barcode
The barcode (for example, ISBN, UPC, or GTIN) associated with the variant.
```
Maybe<Scalars['String']['output']>
```
compareAtPrice
The compare at price of the variant. This can be used to mark a variant as on sale, when `compareAtPrice` is higher than `price`.
```
Maybe<MoneyV2>
```
compareAtPriceV2
The compare at price of the variant. This can be used to mark a variant as on sale, when `compareAtPriceV2` is higher than `priceV2`.
```
Maybe<MoneyV2>
```
components
List of bundles components included in the variant considering only fixed bundles.
```
ProductVariantComponentConnection
```
currentlyNotInStock
Whether a product is out of stock but still available for purchase (used for backorders).
```
boolean
```
groupedBy
List of bundles that include this variant considering only fixed bundles.
```
ProductVariantConnection
```
id
A globally-unique ID.
```
string
```
image
Image associated with the product variant. This field falls back to the product image if no image is available.
```
Maybe<Image>
```
metafield
A [custom field](https://shopify.dev/docs/apps/build/custom-data), including its `namespace` and `key`, that's associated with a Shopify resource for the purposes of adding and storing additional information.
```
Maybe<Metafield>
```
metafields
A list of [custom fields](/docs/apps/build/custom-data) that a merchant associates with a Shopify resource.
```
Array<Maybe<Metafield>>
```
price
The product variant’s price.
```
MoneyV2
```
priceV2
The product variant’s price.
```
MoneyV2
```
product
The product object that the product variant belongs to.
```
Product
```
quantityAvailable
The total sellable quantity of the variant for online sales channels.
```
Maybe<Scalars['Int']['output']>
```
quantityPriceBreaks
A list of quantity breaks for the product variant.
```
QuantityPriceBreakConnection
```
quantityRule
The quantity rule for the product variant in a given context.
```
QuantityRule
```
requiresComponents
Whether a product variant requires components. The default value is `false`. If `true`, then the product variant can only be purchased as a parent bundle with components.
```
boolean
```
requiresShipping
Whether a customer needs to provide a shipping address when placing an order for the product variant.
```
boolean
```
selectedOptions
List of product options applied to the variant.
```
Array<SelectedOption>
```
sellingPlanAllocations
Represents an association between a variant and a selling plan. Selling plan allocations describe which selling plans are available for each variant, and what their impact is on pricing.
```
SellingPlanAllocationConnection
```
shopPayInstallmentsPricing
The Shop Pay Installments pricing information for the product variant.
```
Maybe<ShopPayInstallmentsProductVariantPricing>
```
sku
The SKU (stock keeping unit) associated with the variant.
```
Maybe<Scalars['String']['output']>
```
storeAvailability
The in-store pickup availability of this variant by location.
```
StoreAvailabilityConnection
```
taxable
Whether tax is charged when the product variant is sold.
```
boolean
```
title
The product variant’s title.
```
string
```
unitPrice
The unit price value for the variant based on the variant's measurement.
```
Maybe<MoneyV2>
```
unitPriceMeasurement
The unit price measurement for the variant.
```
Maybe<UnitPriceMeasurement>
```
weight
The weight of the product variant in the unit system specified with `weight_unit`.
```
Maybe<Scalars['Float']['output']>
```
weightUnit
Unit of measurement for weight.
```
WeightUnit
```

MoneyV2

Supports MoneyV2 from both Storefront API and Customer Account API. The APIs may have different CurrencyCode enums (e.g., Customer Account API added USDC in 2025-10, but Storefront API doesn't support USDC in 2025-10). This union type ensures Money component works with data from either API.

StorefrontApiMoneyV2 | CustomerAccountApiMoneyV2

Examples

import {useLoaderData} from 'react-router';

import {useOptimisticVariant} from '@shopify/hydrogen';

export async function loader({context}) {

return {

product: await context.storefront.query('/** product query **/'),

// Note that variants does not need to be awaited to be used by `useOptimisticVariant`

variants: context.storefront.query('/** variants query **/'),

};

}

function Product() {

const {product, variants} = useLoaderData();

// The selectedVariant optimistically changes during page

// transitions with one of the preloaded product variants

const selectedVariant = useOptimisticVariant(

product.selectedVariant,

variants,

);

// @ts-ignore

return <ProductMain selectedVariant={selectedVariant} />;

}

Examples

Example code

JavaScript

import {useLoaderData} from 'react-router';
import {useOptimisticVariant} from '@shopify/hydrogen';

export async function loader({context}) {
  return {
    product: await context.storefront.query('/** product query **/'),
    // Note that variants does not need to be awaited to be used by `useOptimisticVariant`
    variants: context.storefront.query('/** variants query **/'),
  };
}

function Product() {
  const {product, variants} = useLoaderData();

  // The selectedVariant optimistically changes during page
  // transitions with one of the preloaded product variants
  const selectedVariant = useOptimisticVariant(
    product.selectedVariant,
    variants,
  );

  // @ts-ignore
  return <ProductMain selectedVariant={selectedVariant} />;
}

TypeScript

import {useLoaderData} from 'react-router';
import {LoaderFunctionArgs} from 'react-router';
import {useOptimisticVariant} from '@shopify/hydrogen';

export async function loader({context}: LoaderFunctionArgs) {
  return {
    product: await context.storefront.query('/** product query */'),
    // Note that variants does not need to be awaited to be used by `useOptimisticVariant`
    variants: context.storefront.query('/** variants query */'),
  };
}

function Product() {
  const {product, variants} = useLoaderData<typeof loader>();

  // The selectedVariant optimistically changes during page
  // transitions with one of the preloaded product variants
  const selectedVariant = useOptimisticVariant(
    product.selectedVariant,
    variants,
  );

  // @ts-ignore
  return <ProductMain selectedVariant={selectedVariant} />;
}

Anchor to RelatedRelated

VariantSelector

useOptimisticCart

Was this page helpful?