@shopify/hydrogen 2026.10.0-preview.4 → 2026.10.0

package/skills/hydrogen-variant-form/SKILL.md

@@ -106,8 +106,14 @@ When creating a product detail page, use the app's existing route convention whe
 
 Before building product UI, check whether this skill has a reference file for the app's framework in `references/`. If one exists, read it and use that framework binding or route pattern first.
 
+- `references/react.md` — React Router (`Link`, `useNavigate`, `useLocation`).
+- `references/nextjs.md` — Next.js App Router (`next/link`, `next/navigation`).
+- `references/nuxt.md` — Nuxt (`NuxtLink`, Vue Router).
+
 If there is no matching reference, use `createProductFormStore` from `@shopify/hydrogen` directly, subscribe with the framework's reactivity primitive, and own hydration, URL sync, and `destroy()` yourself. Packaged bindings are thin wrappers over this same store — apply every rule and anti-pattern below; do not invent a different contract.
 
+For example, in SolidStart or SvelteKit, write one select function that calls `store.selectOption(name, value)` and, when the result is not `invalid`, navigates once with the router (replace the history entry, keep scroll). This function takes the place of the provider `onSelect`. Render existing same-product values as native `<a href>` links. In the link click handler, apply the guard from the rules below, call `event.preventDefault()`, and then call your select function. The router's own link handling skips a click that is already prevented, so your select function is the only client navigation.
+
 ## Hydration
 
 When the product data changes (e.g. after a URL navigation triggers a data refetch), the store must be hydrated with the new product — not recreated. `hydrate(product, opts?)` replaces the product data, clears the decoded variant cache, and recomputes state. The new product's `selectedOrFirstAvailableVariant` takes priority; if absent, falls back to explicitly provided `opts.selectedOptions`, then to the selection that was active before hydration.
@@ -156,9 +162,12 @@ Pass `style: "variant"` with a resolved `variant` to emit a shareable `?variant=
 
 ### Selection and navigation
 
-- **With provider bindings, put URL navigation in the provider `onSelect` callback.** Do not navigate inside each same-product option button. Let `register("optionValue", ...)` call `selectOption`; the provider receives the valid selection result and owns URL sync from there.
+- **With provider bindings, put URL navigation in the provider `onSelect` callback.** Do not navigate inside each same-product option control. Let `register("optionValue", ...)` call `selectOption`; the provider receives the valid selection result and owns URL sync from there.
 - **ALWAYS use URL-based variant selection in URL-routing apps.** When the buyer selects an option, navigate to the URL representing that selection — replacing the history entry and without resetting scroll position. The URL is the durable source of truth — the data loader reads the selection from the URL, queries the Storefront API, and the response hydrates the store when a reload or revalidation happens.
-- **Same-product option values must degrade to GET links (no JS).** In URL-routing apps, render each same-product option value as a real link (the framework's link component or `<a href>`) whose `href` is the option URL for that value, built from `value.selectedOptions` — not a bare `<button onClick>`. The `href` is the no-JS path: with scripting off, activating it issues a GET to the option URL, the loader reads the params, queries the Storefront API, and the server renders the newly selected variant. Hydration enhances the same element — the registered `register("optionValue", ...)` handler calls `selectOption` and the provider's `onSelect` replaces the URL client-side (no full reload). Because the `href` and the client navigation resolve to the same option URL, behavior is identical with or without JS. On a hydrated click the element both runs the registered handler (which calls `selectOption`) and performs its own link navigation to that same URL, so keep the provider `onSelect` idempotent — the redundant navigation is a harmless no-op. An option control that is button-/`onClick`-only renders nothing a no-JS shopper can act on, stranding them on the default variant. Non-existent combinations (`exists: false`) have no valid option URL to degrade to; render those as a disabled `<button>`, not a link. (Cross-product values are already links; this brings same-product values to parity.)
+- **Same-product option values must degrade to GET links (no JS).** In URL-routing apps, render each existing same-product option value (`exists: true`) as a real link (the framework's link component or `<a href>`) whose `href` is the option URL for that value, built from `value.selectedOptions` — not a bare `<button onClick>`. The `href` is the no-JS path: with scripting off, activating it issues a GET to the option URL, the loader reads the params, queries the Storefront API, and the server renders the newly selected variant. A button-/`onClick`-only control gives a no-JS shopper nothing to act on, so they stay on the default variant. Non-existent combinations (`exists: false`) have no valid option URL; render those as a disabled `<button>`, not a link. Cross-product values are links too (see Combined listings).
+- **After hydration, the provider `onSelect` is the only client navigation.** Handle the same-product link click yourself. For a plain primary click — not already prevented, `event.button === 0`, no Meta, Ctrl, Shift, or Alt key, and the link `target` is empty or `_self` — call `event.preventDefault()`, then call `onClick()` from `register("optionValue", ...)` (or your select function when you use the store directly). The registered handler calls `selectOption`, and the provider `onSelect` replaces the URL one time. `preventDefault()` stops the link and the framework router from navigating a second time. Do not call `navigate()` yourself in addition to the registered handler. Keep the selection callback safe to repeat, including clicks on already-selected values. Each framework reference shows the click hook to use.
+- **Leave other link clicks native.** Modifier-key clicks, middle clicks, and links with a `target` other than `_self` must keep the browser's link behavior (for example, open the option URL in a new tab). They must not change the selection on the current page. Do not put `download` on option links; a guard on a native `<a>` also returns early when the link has `download`. Do not spread `register("optionValue", ...)` onto a link: the spread `onClick` runs for every click, including modifier-key clicks, and does not stop the link's own navigation.
+- **Use the same query base for the `href` and for the selection callback** (provider `onSelect`, or your select function when you use the store directly). Pass the current URL search params as `base` to `buildProductSelectionSearchParams` in both places. Then the no-JS link and the hydrated navigation go to the same URL, and unrelated params (`?ref=campaign`) stay on both paths.
 - **ALWAYS use the `selectOption` return value for navigation, not a reactive effect on state.** `selectOption` returns the result synchronously. Use the returned `selectedOptions` to construct the next URL immediately. Reacting to derived state (e.g. `selectedOptions` from the store) instead introduces an unnecessary update cycle and risks stale values. Framework bindings may wrap this as an `onSelect` callback — the principle is the same.
 - **Skip data refetch only when the resolved local state is sufficient.** When `selectOption` returns `resolved`, the selected variant is already in the local cache. It is safe to skip revalidation only if the route does not need fresh loader data for other UI. When a complete selection returns `unresolved`, fetch or otherwise resolve the exact variant before treating the selection as complete.
 - **NEVER call `selectOption` for combined-listing cross-product values.** When `value.handle !== product.handle`, the value belongs to a different product. Render it as a navigation element (anchor or link component) that navigates to the other product's URL — not a button that calls `selectOption`. The store only knows about the current product's variant matrix.
@@ -167,6 +176,7 @@ Pass `style: "variant"` with a resolved `variant` to emit a shareable `?variant=
 
 - **ALWAYS check `value.handle` against the current `product.handle`.** If they differ, the option value points to a different product in a combined listing. The UI must navigate to that product (full page navigation or a link component), not call `selectOption`.
 - **Use the framework's client-side link component for cross-product values when one exists.** Use the app's idiomatic navigation primitive. Use a raw `<a>` only when that is the app's established routing convention.
+- **Keep focus on the activated value across a cross-product navigation.** After the switch, the activated value is a same-product value on the new product page. Render same-product and cross-product values with the same element type, so a framework that keeps the route component mounted across a param change (React Router) reconciles the node in place and focus stays on it. Where the framework remounts the page on a handle change (Next.js App Router keys the `[handle]` segment by its value), record the activated value before navigating and focus its same-product link as the new page mounts. Otherwise focus drops to `<body>`, and keyboard and screen-reader users lose their place and never hear the new selection.
 - **Preserve non-option query params on combined-listing links.** When constructing the URL for a combined-listing link, carry forward existing search params (e.g. `?ref=campaign`) and replace only the option params. Use `buildProductSelectionSearchParams` with the current product's option names as `optionNames` — it deletes all option params (and any stale `variant` param) first, then sets the new ones, preventing stale params when combined-listing products have different option names.
 - **Ignore selected options that are not in the current product option matrix.** Divergent combined-listing child products can have different option names. A stale `Color=Black` param must not constrain a child product whose options are `Size` and `Mount`.
 
@@ -204,11 +214,11 @@ Pass `style: "variant"` with a resolved `variant` to emit a shareable `?variant=
 
 1. **Pre-selected variant** — When the product has a `selectedOrFirstAvailableVariant`, the corresponding option values are marked as selected on first render. The variant's price and details are displayed. `selectedVariant` on the state is non-null.
 2. **No pre-selected variant** — When `selectedOrFirstAvailableVariant` is `null`, no option values are selected. `selectedVariant` is `null`. The add-to-cart button shows "Select options" (or equivalent) and is disabled.
-3. **URL-driven selection** — When the URL encodes a variant selection (e.g. via option params like `?Color=Blue&Size=Small`), the data loader resolves the selection and passes it to the Storefront API query. The returned `selectedOrFirstAvailableVariant` reflects the URL selection, and the store initializes with those options selected.
+3. **URL-driven selection** — When the URL encodes a variant selection (e.g. via option params like `?Color=Blue&Size=Small`), the data loader resolves the selection and passes it to the Storefront API query. The returned `selectedOrFirstAvailableVariant` reflects the URL selection, and the store initializes with those options selected. The page shows the shopper which option values are selected (visible styling or text), in addition to `aria-current` or `aria-pressed`.
 
 ### Option selection
 
-4. **Select a value** — Click an option value button. The value becomes selected (visually indicated). If the selection resolves to a variant, the price and variant details update immediately. `selectedVariant` updates on the state. In URL-routing apps, the URL updates to reflect the new selection without a scroll reset.
+4. **Select a value** — Click an option value. The value becomes selected (visually indicated). If the selection resolves to a variant, the price and variant details update immediately. `selectedVariant` updates on the state. In URL-routing apps, the URL updates to reflect the new selection without a scroll reset.
 5. **Multi-option selection** — On a product with Size and Color options, select Size=Large then Color=Blue. Both selections are reflected in the state. The resolved variant matches Large/Blue.
 6. **Symmetric availability** — On a product where Medium/Olive is unavailable but Medium/Green is available, selecting Color=Olive marks Size=Medium as `available: false`; selecting Color=Green marks Size=Medium as `available: true`.
 7. **Switch within an option** — With Color=Red selected, click Color=Blue. The selection switches; Red is deselected, Blue is selected. Only one value per option is selected at a time.
@@ -218,8 +228,8 @@ Pass `style: "variant"` with a resolved `variant` to emit a shareable `?variant=
 
 ### Combined listings
 
-11. **Cross-product value** — An option value where `value.handle !== product.handle` renders as a navigation element (anchor or link component), not a button. Clicking it navigates to the other product's page with the appropriate option params.
-12. **Same-product value** — An option value where `value.handle === product.handle` renders as a GET link to its option URL and spreads `register("optionValue", ...)`. With JavaScript disabled the link navigates and the server resolves the variant; hydrated, the registered handler calls `selectOption` and the provider syncs the URL client-side.
+11. **Cross-product value** — An option value where `value.handle !== product.handle` renders as a navigation element (anchor or link component), not a button. Clicking it navigates to the other product's page with the appropriate option params. After the navigation, focus is on the activated value's link on the new product page and the scroll position is unchanged.
+12. **Same-product value** — An option value where `value.handle === product.handle` renders as a GET link to its option URL enhanced by the `register("optionValue", ...)` click handler. With JavaScript disabled the link navigates and the server resolves the variant. Hydrated, a plain click calls `selectOption`, the provider syncs the URL client-side, and the link's own navigation does not run, so a resolved selection issues no loader request. A Cmd- or Ctrl-click opens the option URL in a new tab and leaves the current page's selection unchanged.
 13. **Preserved params** — When navigating via a combined-listing link, non-option query params from the current URL are preserved in the destination URL.
 
 ### Hydration
@@ -261,12 +271,20 @@ Pass `style: "variant"` with a resolved `variant` to emit a shareable `?variant=
 
 34. **Reset to initial state** — Calling `reset()` restores the store to the product and selected options it was created with. All user selections are discarded.
 
+### Progressive links
+
+35. **No JavaScript** — With JavaScript disabled, activating an existing option link issues a GET to its option URL, and the server renders that selection. If the app cannot render the product page without JavaScript, record that path as not available. Do not record it as a pass.
+36. **One navigation** — Hydrated, a plain click on an existing same-product option link causes exactly one client navigation. That navigation replaces the history entry, keeps scroll, and does not reload the page. The selection updates.
+37. **Unrelated params kept** — With `?ref=campaign` in the URL, option link `href` values and the URL after a hydrated selection both keep `ref=campaign`.
+38. **Modifier and new-tab clicks** — A Cmd/Ctrl click, a middle click, or a link with `target="_blank"` opens the option URL natively. The current page's selection and URL do not change.
+
 ---
 
 ## Anti-patterns
 
 - **Using reactive effects on state to sync selection to URL.** The `selectOption` return value provides the selection result synchronously. Reacting to `state.selectedOptions` instead introduces an extra update cycle and can fire with stale values.
-- **Navigating inside same-product option buttons.** Do not destructure `onClick` / `onChange` from `register("optionValue", ...)`, call `navigate()`, and then call the registered handler manually. This bypasses the provider `onSelect` contract and can navigate from stale or invalid data.
+- **Navigating inside same-product option controls.** Do not call `navigate()` in an option click handler and then also call the registered handler. This bypasses the provider `onSelect` contract and can navigate from stale or invalid data. A guarded link handler that calls `event.preventDefault()` and then only `registered.onClick()` is correct.
+- **Spreading `register("optionValue", ...)` onto a link unguarded.** The link runs the registered handler and then its own navigation. The second navigation refetches the loader a resolved selection skipped, and a Cmd- or Ctrl-click both opens a new tab and changes the current page. Run the handler only for a plain primary click and cancel the link's navigation.
 - **Button-/onClick-only same-product option values.** A same-product option value rendered as `<button onClick={selectOption}>` with no `href` is dead without JavaScript — a no-JS shopper cannot switch variants and is stuck on the default. Render it as a GET link to the option URL and let the registered handler enhance it; the `href` is the progressive-enhancement fallback.
 - **Using raw anchors when the framework has a client-side link component.** Raw `<a>` tags lose client-router behavior such as scroll preservation, pending navigation state, prefetching, and route transitions. Use the app's established link component unless raw anchors are the framework convention.
 - **Putting variant selection inside the add-to-cart form.** Variant selection is button/link interactions that update store state. The add-to-cart form submits `merchandiseId` and `quantity` to the cart. Mixing them creates ambiguous form semantics and breaks progressive enhancement.

package/skills/hydrogen-variant-form/references/nextjs.md

@@ -5,6 +5,7 @@
 - Server Page
 - Client Details Component
 - Same-Product And Cross-Product Values
+- No-JavaScript Limits
 - Add To Cart
 
 Product data is fetched in the server page. Variant selection and add-to-cart live in a `"use client"` component because they use `ProductProvider`, browser routing, and cart forms.
@@ -146,23 +147,30 @@ Wrap this tree in the app's `CartProvider` from `hydrogen-cart-ui`; `ProductProv
 
 ## Same-Product And Cross-Product Values
 
-Render same-product option values as GET links (`next/link`) so variant selection degrades without JavaScript (the skill's GET-links rule and accessibility guidance cover the `aria-current`, idempotent-`onSelect`, and no-JS rationale). The `href` is the option URL built from `value.selectedOptions`; spread `register("optionValue", ...)` to enhance the link so a hydrated click selects client-side via the provider's `onSelect`. Keep sold-out-but-existing values interactive and derive their visual treatment from `value.available`. Render non-existent combinations (`exists: false`) as a disabled `<button>` instead of a link.
+Render existing same-product option values as GET links (`next/link`) so variant selection degrades without JavaScript (see the skill's GET-links and Accessibility rules for the no-JS fallback and `aria-current`, and its "provider `onSelect` is the only client navigation" rule for `onSelect`). The `href` is the option URL built from `value.selectedOptions`, with the same `searchParams` base as the provider `onSelect`. Do not spread `register("optionValue", ...)` onto `Link`. Use `onNavigate` instead: call `event.preventDefault()` to cancel the `Link` navigation, then call `registered.onClick()` so the provider `onSelect` is the only navigation. Next.js does not call `onNavigate` for modifier-key clicks, a `target` other than `_self`, or links with `download`, so those clicks stay native. Cancel navigation and call the registered handler only on same-product values; cross-product links can use `onNavigate` to record focus as shown below. Keep sold-out-but-existing values interactive and derive their visual treatment from `value.available`. Render non-existent combinations (`exists: false`) as a disabled `<button>` instead of a link.
 
 ```tsx
+const searchParams = useSearchParams();
+
 <Link
   href={variantUrl(product, value.selectedOptions, value.handle, searchParams)}
-  replace
   scroll={false}
+  ref={(node) => focusIfPending(node, product.handle, option.name, value.name)}
   aria-current={value.selected ? "true" : undefined}
   data-available={value.available ? "true" : "false"}
-  {...register("optionValue", { optionName: option.name, value: value.name })}
+  onNavigate={(event) => {
+    // The provider owns URL sync; stop Link from navigating a second time.
+    event.preventDefault();
+    const registered = register("optionValue", { optionName: option.name, value: value.name });
+    registered.onClick();
+  }}
 >
   {value.name}
   {!value.available ? <span className="sr-only"> (Sold out)</span> : null}
 </Link>
 ```
 
-Cross-product combined-listing values point at a different `value.handle` and navigate to that product. Prefer `next/link`; if using a button for cross-product navigation, keep it clearly outside the add-to-cart form and call `router.replace(...)`. Both use the same URL helper:
+Cross-product combined-listing values point at a different `value.handle` and navigate to that product. Render them as a normal `next/link` with `scroll={false}`. Use `onNavigate` only to record focus for the new page, not to select an option or cancel navigation. Both link types use the same URL helper:
 
 ```tsx
 import { buildProductSelectionSearchParams, type SelectedOption } from "@shopify/hydrogen";
@@ -183,6 +191,33 @@ function variantUrl(
 }
 ```
 
+Next.js keys the `[handle]` segment by its value, so a cross-product navigation unmounts the product component and the focused link with it, and `scroll={false}` also turns off the router's own focus handling. Keep focus on the activated value by recording it in module state from the cross-product link's `onNavigate`, which does not fire for a Cmd-click, and focusing its same-product link through a callback `ref` as the new page mounts. Module state outlives the remount. A ref or `useState` inside the component does not.
+
+```tsx
+let pendingFocus: { handle: string; optionName: string; value: string } | null = null;
+
+function focusIfPending(node: HTMLAnchorElement | null, handle: string, optionName: string, value: string) {
+  if (!node || pendingFocus?.handle !== handle || pendingFocus.optionName !== optionName || pendingFocus.value !== value) return;
+  pendingFocus = null;
+  node.focus();
+}
+
+<Link
+  href={variantUrl(product, value.selectedOptions, value.handle, searchParams)}
+  scroll={false}
+  onNavigate={() => {
+    pendingFocus = { handle: value.handle, optionName: option.name, value: value.name };
+  }}
+  data-available={value.available ? "true" : "false"}
+>
+  {value.name}
+</Link>
+```
+
+## No-JavaScript Limits
+
+A valid option `href` does not by itself make the product page render without JavaScript. When product content is inside a `<Suspense>` boundary that streams after the first HTML (for example, a root layout that wraps a dynamic app shell in `<Suspense>`), React reveals the streamed content with an inline script. With JavaScript disabled, the shopper can see only the fallback, even though the server resolved the selected variant. Test the no-JS path in your app. If the product page does not render without JavaScript, record that limit; do not report the no-JS option links as verified.
+
 ## Add To Cart
 
 Use the local `hydrogen-shop-pay` skill when adding Shop Pay. Use the local `hydrogen-money` skill for prices.

package/skills/hydrogen-variant-form/references/nuxt.md

@@ -20,19 +20,23 @@ Wrap this tree in the app's `CartProvider` from `hydrogen-cart-ui`; `ProductProv
 
 In `pages/products/[handle].vue`, pass selected options from `getSelectedProductOptions({searchParams})` into the Storefront API query. Use one reusable variant fragment for `firstSelectableVariant`, `selectedOrFirstAvailableVariant`, and `adjacentVariants`; it must include variant `price`, `availableForSale`, `selectedOptions`, and `product { handle title }` so price display and combined-listing navigation work. Use the injected server/client Storefront client from the Nuxt storefront-client recipe.
 
-Wrap the UI:
+Wrap the UI. The provider `onSelect` is the only client navigation for same-product selection; use `router.replace` from `useRouter()`:
 
 ```vue
+<script setup lang="ts">
+import type { ValidProductSelectionResult } from "@shopify/hydrogen/vue";
+import { ProductProvider } from "~/storefront/product";
+import type { ProductData } from "~/storefront/product-types";
+
+const router = useRouter();
+
+function handleSelect(result: ValidProductSelectionResult<ProductData>) {
+  router.replace(variantRoute(result.selectedOptions, result.selectedVariant?.product?.handle));
+}
+</script>
+
 <template>
-  <ProductProvider
-    :product="product"
-    :on-select="
-      (result) =>
-        navigateTo(variantRoute(result.selectedOptions, result.selectedVariant?.product?.handle), {
-          replace: true,
-        })
-    "
-  >
+  <ProductProvider :product="product" :on-select="handleSelect">
     <ProductVariantSelector :product="product" />
     <ProductAddToCart :product="product" />
   </ProductProvider>
@@ -41,42 +45,79 @@ Wrap the UI:
 
 ## Variant Selector
 
-Same-product option values are GET links (`NuxtLink`) so selection degrades without JavaScript; non-existent combinations render as a disabled `<button>`, and cross-product combined-listing values are also links. The skill's GET-links rule and accessibility guidance cover the `aria-current`, idempotent-`onSelect`, and no-JS rationale:
+Same-product option values are GET links so selection degrades without JavaScript; non-existent combinations render as a disabled `<button>`, and cross-product combined-listing values are normal `NuxtLink` links. See the skill's GET-links and Accessibility rules for the no-JS fallback and `aria-current`, and its "provider `onSelect` is the only client navigation" rule for `onSelect`.
+
+For existing same-product values, use `NuxtLink` with `custom` and render the anchor yourself from the slot `href`. Put a guarded `@click` on that anchor: for a plain primary click it calls `event.preventDefault()` and then `onClick()` from `form.register("optionValue", ...)`, so the provider `onSelect` is the only navigation. Other clicks keep native link behavior. Do not call the slot `navigate`. Do not put `@click` on a regular `NuxtLink` to cancel its navigation, and do not `v-bind` the registration onto it; the order of your listener and the link's own navigation is not something to rely on.
+
+This custom-link guard has not been verified in a running Nuxt storefront. Check plain-click, modified-click, and no-JavaScript behavior in your app before treating this path as verified.
 
 ```vue
-<!-- cross-product: navigate to a different product -->
-<NuxtLink
-  v-if="value.handle !== product.handle"
-  :to="variantRoute(value.selectedOptions, value.handle)"
-  replace
->
-  {{ value.name }}
-</NuxtLink>
-
-<!-- same-product, non-existent combination: no option URL to degrade to -->
-<button
-  v-else-if="!value.exists"
-  type="button"
-  disabled
-  :aria-pressed="value.selected"
->
-  {{ value.name }}
-</button>
-
-<!-- same-product, existing value: GET link enhanced by the registered handler -->
-<NuxtLink
-  v-else
-  :to="variantRoute(value.selectedOptions, value.handle)"
-  replace
-  :aria-current="value.selected ? 'true' : undefined"
-  v-bind="form.register('optionValue', { optionName: option.name, value: value.name })"
->
-  {{ value.name }}
-  <template v-if="!value.available"> - Sold out</template>
-</NuxtLink>
+<script setup lang="ts">
+const form = useProductForm();
+
+function handleOptionClick(event: MouseEvent, optionName: string, value: string) {
+  const anchor = event.currentTarget;
+  if (
+    event.defaultPrevented ||
+    event.button !== 0 ||
+    event.metaKey ||
+    event.ctrlKey ||
+    event.shiftKey ||
+    event.altKey ||
+    !(anchor instanceof HTMLAnchorElement) ||
+    (anchor.target !== "" && anchor.target.toLowerCase() !== "_self") ||
+    anchor.hasAttribute("download")
+  ) {
+    return;
+  }
+
+  // The provider owns URL sync; stop the anchor from navigating too.
+  event.preventDefault();
+  const registered = form.register("optionValue", { optionName, value });
+  registered.onClick();
+}
+</script>
+
+<template>
+  <!-- cross-product: navigate to a different product -->
+  <NuxtLink
+    v-if="value.handle !== product.handle"
+    :to="variantRoute(value.selectedOptions, value.handle)"
+    replace
+  >
+    {{ value.name }}
+  </NuxtLink>
+
+  <!-- same-product, non-existent combination: no option URL to degrade to -->
+  <button
+    v-else-if="!value.exists"
+    type="button"
+    disabled
+    :aria-pressed="value.selected"
+  >
+    {{ value.name }}
+  </button>
+
+  <!-- same-product, existing value: GET link with a guarded click -->
+  <NuxtLink
+    v-else
+    v-slot="{ href }"
+    :to="variantRoute(value.selectedOptions)"
+    custom
+  >
+    <a
+      :href="href"
+      :aria-current="value.selected ? 'true' : undefined"
+      @click="handleOptionClick($event, option.name, value.name)"
+    >
+      {{ value.name }}
+      <template v-if="!value.available"> - Sold out</template>
+    </a>
+  </NuxtLink>
+</template>
 ```
 
-Build route query objects with `buildProductSelectionSearchParams`, passing the product option names as `optionNames`. Convert Nuxt's current route query to `URLSearchParams` for `base` by appending every scalar or array value, then convert the returned params back to a Nuxt query object while preserving repeated keys. This preserves non-option params while removing stale option params and the reserved `variant` param.
+`variantRoute(selectedOptions, handle)` returns `{ path, query }`. Build the query with `buildProductSelectionSearchParams`, passing the product option names as `optionNames`. Convert Nuxt's current route query to `URLSearchParams` for `base` by appending every scalar or array value, then convert the returned params back to a Nuxt query object while preserving repeated keys. Use the current route query as `base` both for link `href` values and for `onSelect`. This preserves non-option params while removing stale option params and the reserved `variant` param.
 
 ## Add To Cart
 

package/skills/hydrogen-variant-form/references/react.md

@@ -1,4 +1,6 @@
-# React Product Bindings
+# React Router Product Bindings
+
+This reference uses React Router (`Link`, `useNavigate`, `useLocation`). For Next.js App Router, read `nextjs.md`.
 
 Create typed React product bindings once from `@shopify/hydrogen/react`, usually in a shared product module:
 
@@ -10,19 +12,29 @@ export const { ProductProvider, useProductForm } =
   createProductComponents<ProductData>();
 ```
 
-Use the provider's `onSelect` callback for same-product URL sync:
+Use the provider's `onSelect` callback for same-product URL sync. Pass the current search params as the `variantUrl` base, so the URL keeps unrelated params and matches the option link `to`:
 
 ```tsx
+const navigate = useNavigate();
+const location = useLocation();
+
 <ProductProvider
   product={product}
   onSelect={(result) => {
     void navigate(
       toRouterLocation(
-        variantUrl(product, result.selectedOptions, result.selectedVariant?.product?.handle),
+        variantUrl(
+          product,
+          result.selectedOptions,
+          result.selectedVariant?.product?.handle,
+          new URLSearchParams(location.search),
+        ),
       ),
       {
         replace: true,
         preventScrollReset: true,
+        // Optional: skip loader revalidation when the variant resolved locally.
+        ...(result.status === "resolved" ? { defaultShouldRevalidate: false } : {}),
       },
     );
   }}
@@ -31,18 +43,42 @@ Use the provider's `onSelect` callback for same-product URL sync:
 </ProductProvider>
 ```
 
-If a route should skip loader revalidation for locally resolved selections, use the framework's supported route-level revalidation API. Do not pass unsupported revalidation flags to `navigate()`.
+`variantUrl(product, selectedOptions, handle, base)` calls `buildProductSelectionSearchParams` with the product option names and `base`, then returns `/products/{handle}?{params}`; `handle` defaults to `product.handle`.
+
+`defaultShouldRevalidate: false` is optional. Use it only for `resolved` selections, only when no other UI on the route needs fresh loader data, and only if the installed React Router supports it. Leave it out for `unresolved` selections, so the loader resolves the exact variant. A route `shouldRevalidate` export still makes the final decision.
 
-Same-product option values are GET links so selection works without JavaScript (the skill's GET-links rule and accessibility guidance cover the `aria-current`, idempotent-`onSelect`, and no-JS rationale). The `to` is the option URL built from `value.selectedOptions`; spreading the registered handlers enhances the link so a hydrated click selects client-side through the provider's `onSelect`. Keep sold-out-but-existing values interactive and derive their visual treatment from `value.available`:
+Same-product option values are GET links so selection works without JavaScript. The `to` is the option URL built from `value.selectedOptions` with the same base as `onSelect`. Do not spread the registration onto `Link`. Pass a guarded `onClick` instead: for a plain primary click it calls `event.preventDefault()` and then `registered.onClick()`. React Router's `Link` does not navigate when the event is already prevented, so the provider `onSelect` is the only navigation. Other clicks keep native link behavior. Keep sold-out-but-existing values interactive and derive their visual treatment from `value.available`:
 
 ```tsx
+const location = useLocation();
+const baseParams = useMemo(() => new URLSearchParams(location.search), [location.search]);
+
+const registered = register("optionValue", { optionName: option.name, value: value.name });
+const onSelectLink = (event: MouseEvent<HTMLAnchorElement>) => {
+  if (
+    event.defaultPrevented ||
+    event.button !== 0 ||
+    event.metaKey ||
+    event.altKey ||
+    event.ctrlKey ||
+    event.shiftKey ||
+    (event.currentTarget.target && event.currentTarget.target !== "_self")
+  ) {
+    return;
+  }
+
+  // The provider owns URL sync; stop Link from navigating a second time.
+  event.preventDefault();
+  registered.onClick();
+};
+
 <Link
-  to={toRouterLocation(variantUrl(product, value.selectedOptions, value.handle))}
+  to={toRouterLocation(variantUrl(product, value.selectedOptions, value.handle, baseParams))}
   replace
   preventScrollReset
   aria-current={value.selected ? "true" : undefined}
   data-available={value.available ? "true" : "false"}
-  {...register("optionValue", { optionName: option.name, value: value.name })}
+  onClick={onSelectLink}
 >
   {value.name}
   {!value.available ? <span className="sr-only"> (Sold out)</span> : null}
@@ -57,11 +93,11 @@ Non-existent combinations (`exists: false`) render as a disabled `<button>` inst
 </button>
 ```
 
-Cross-product option values are framework links that reuse the same URL helper:
+Cross-product option values are framework links that reuse the same URL helper and base. They do not call the registered handler. Rendering them as `<Link>` like the same-product values is what keeps focus across the switch. React Router keeps the route component mounted when only `:handle` changes, so React reconciles the activated link in place. A cross-product `<Link>` next to a same-product `<button>` would change element type on the activated control after the navigation, React would remount it, and focus would drop to `<body>`.
 
 ```tsx
 <Link
-  to={toRouterLocation(variantUrl(product, value.selectedOptions, value.handle))}
+  to={toRouterLocation(variantUrl(product, value.selectedOptions, value.handle, baseParams))}
   preventScrollReset
   data-available={value.available ? "true" : "false"}
 >