@shopify/hydrogen 2026.4.5 → 2026.10.0-preview.2

package/skills/hydrogen-collection-browser/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: hydrogen-collection-browser
+description: >
+  Guide for building collection and search browsing UI with @shopify/hydrogen.
+  Use when creating, modifying, or reviewing collection routes, search results,
+  product grids, filters, sort controls, active filter chips, or URL-synced
+  browse state in storefront frameworks.
+---
+
+# Collection And Search Browsing
+
+Hydrogen's collection primitive manages browse intent: filters, sort, URL params, and loading status. It does not own product data. The framework loader/server component owns Storefront API queries and passes products plus available filters into UI.
+
+Use this skill for:
+
+- `/collections`, `/collections/:handle`, and `/search` routes.
+- Product grid filtering and sorting.
+- Active filter chips and clear links.
+- No-JS GET form fallbacks for filters and sort.
+- Search-result pages that reuse collection browse state.
+
+## Framework References
+
+Before building 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.
+
+If there is no matching reference, use `createCollectionStore` plus the `parseCollectionParams`/`serializeCollectionParams`/`getFilterRemovalUrl`/`isFilterInputActive` helpers from `@shopify/hydrogen` directly, and apply the UI and search rules below with the framework's own form, route, and reactivity primitives.
+
+## Data Contract
+
+Server data should include:
+
+- Collection/search identity: collection `handle`, or `search:${term}` for search pages.
+- `dataSearch`: the exact search string used for the server query.
+- `products`: Storefront API product nodes shaped for the product card.
+- `availableFilters`: normalized filter metadata from `products.filters` or `search.productFilters`.
+- Optional `totalCount` and `pageInfo` for search or pagination UI.
+
+Use `parseCollectionParams(searchParams)` before Storefront API queries. Pass parsed `filters`, `sortKey`, and `reverse` into `collection.products(...)` or `search(...)`.
+
+## UI Rules
+
+- Use the framework binding when a matching reference exists. Otherwise, use the core store directly. Do not hand-roll browse state with component state.
+- The browse form must carry both `method="get"` **and** an explicit `action` (the collection/search route URL, e.g. `action="/collections/shoes"` or the search route) so filters and sort degrade to a real GET submit without JavaScript. `formProps()` only wires the submit handler — it does not set `method` or `action` — so render both literally; the helper cannot infer the route.
+- Choose controls at the filter-group level: `PRICE_RANGE` renders min/max number inputs; `LIST` and `BOOLEAN` render value checkboxes. A price value serializes to two params, so never use the number of serialized entries to decide whether to render the group. Use the fixed `filter.v.price.gte` and `filter.v.price.lte` names for range inputs; continue deriving checkbox names and values from `value.input`.
+- Use `formProps()` on the browse form: spread it, then add the literal `method="get"` and `action`. Submit checkboxes and `<select>` controls on change. Submit price inputs on blur only when the value changed, and let Enter blur the input. Never submit on every keystroke.
+- Render a `noscript` submit button for filter sidebars that auto-submit when hydrated.
+- Render "load more" / pagination as a GET link (the framework's link component) carrying the next-page cursor (e.g. `?after=<endCursor>`), so it works without JavaScript. Hydration may upgrade it to append-in-place; the bare link must still load the next page server-side (it replaces the page rather than appending when JS is off).
+- Clear both `before` and `after` whenever filters or sorting change so the new browse state starts from its first page.
+- Show stale products with a pending visual state while `state.status === "loading"`; do not replace the grid with a skeleton.
+- Serialize active filter chips from `serializeCollectionParams(state)` and remove filters with `getFilterRemovalUrl(...)`.
+- Use `isFilterInputActive(state.filters, value.input)` to mark checked filter inputs.
+- Treat each Storefront API `FilterValue.input` JSON string as the authoritative filter identity. To render one checkbox, parse that JSON into a `ProductFilter`, wrap it as `{ filters: [filter], sortKey: undefined, reverse: false }`, and pass it to `serializeCollectionParams(...)` for the field name/value. Do not derive filter shapes or param names from filter IDs, labels, or types.
+- Build sort option values with `getSortByValue(...)`; it emits the Liquid-compatible `sort_by` strings that `parseCollectionParams()` understands.
+- Treat availability and other single-choice filters as mutually exclusive when the Storefront filter input serializes to the same param name.
+
+## Search Rules
+
+- Keep the search term in `q`.
+- Use a collection handle like `search:${term}` so a new term rebuilds the browse store and does not carry old filters.
+- Keep `q` as a hidden input inside the filter/sort form.
+- Map unsupported search sorts back to `RELEVANCE`; only `PRICE` uses `reverse`.
+- Empty search terms should return an empty product list and no filters rather than querying Storefront API.
+- The search input is uncontrolled (`defaultValue={term}`) so the no-JS GET submit works; add `key={term}` so navigation (e.g. "Clear search" → `/search`) resets it. Safe because `term` changes only on submit/navigation, not while typing — do **not** put `key={term}` on a controlled input that updates the term per keystroke (focus loss).
+
+## Anti-Patterns
+
+- Do not use router query objects when filter param names contain dots, unless the framework preserves dotted keys literally.
+- Do not compute filter URLs manually when Hydrogen helpers can serialize/remove filters.
+- Do not write a custom mapping table from `ProductFilter` shapes to URL params. `serializeCollectionParams(...)` already maps supported shapes such as `available`, `productType`, `productVendor`, `tag`, `variantOption`, product metafields, variant metafields, and price into Liquid-compatible params.
+- Do not synthesize Storefront API `ProductFilter` objects from display metadata. `value.input` already contains the supported filter shape.
+- Do not store products in the collection store; products come from the framework data response.
+- Do not clear non-filter params such as `q`, campaign params, or variant params unless the route explicitly owns them.
+
+## Verify
+
+- Filtering and sorting update the URL without scroll reset when hydrated.
+- Checkbox filters and `PRICE_RANGE` min/max controls both render, apply, and persist after reloading the URL.
+- Reloading the filtered URL server-renders the same filtered state.
+- With JavaScript disabled, checking filters and submitting the form loads the filtered URL.
+- With JavaScript disabled, the load-more / pagination link loads the next page server-side.
+- Active filter chips remove only one filter and preserve unrelated params.
+- Search filters preserve `q`.
+- Back/forward navigation settles loading state.

package/skills/hydrogen-collection-browser/references/nextjs.md

@@ -0,0 +1,118 @@
+# Next.js App Router
+
+Use a client component for browse controls. Server pages fetch products and filters, then pass the snapshot into the client browser component.
+
+## Server Page
+
+In `app/collections/[handle]/page.tsx`:
+
+```tsx
+export default async function CollectionPage({
+  params,
+  searchParams,
+}: {
+  params: Promise<{ handle: string }>;
+  searchParams: Promise<Record<string, string | string[] | undefined>>;
+}) {
+  const { handle } = await params;
+  const urlSearch = toURLSearchParams(await searchParams);
+  const storefront = await getStorefrontClient();
+  const result = await queryCollection({ storefrontClient: storefront, handle, searchParams: urlSearch });
+  if (!result) notFound();
+
+  return <CollectionBrowser mode="collection" {...result} dataSearch={urlSearch.toString()} />;
+}
+
+function toURLSearchParams(input: Record<string, string | string[] | undefined>) {
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(input)) {
+    if (Array.isArray(value)) {
+      for (const item of value) params.append(key, item);
+    } else if (value != null) {
+      params.set(key, value);
+    }
+  }
+  return params;
+}
+```
+
+The page may be dynamic when it reads request-scoped Storefront client data or search params.
+
+## Client Browser
+
+In a `"use client"` component:
+
+```tsx
+import { CollectionProvider, useCollection, useCollectionForm } from "@shopify/hydrogen/react";
+import { usePathname, useRouter, useSearchParams } from "next/navigation";
+
+export function CollectionBrowser(props: Props) {
+  const router = useRouter();
+  const pathname = usePathname();
+  const searchParams = useSearchParams();
+  const urlSearch = searchParams.toString();
+
+  return (
+    <CollectionProvider
+      // dataSearch is the server-committed search string for the loaded products.
+      // urlSearch is the live browser URL and can be ahead during transitions.
+      data={{ handle: props.handle, dataSearch: props.dataSearch }}
+      urlSearch={urlSearch}
+      onChange={(search) => {
+        const href = `${pathname}${search}`;
+        if (urlSearch) router.replace(href, { scroll: false });
+        else router.push(href, { scroll: false });
+        router.refresh();
+      }}
+    >
+      <BrowserContent {...props} />
+    </CollectionProvider>
+  );
+}
+```
+
+`router.refresh()` is important when the client URL changes before the React Server Component payload catches up. Under Partial Prerendering, a `<Link>` to a changed `searchParams` (active-filter chips, clear-all, load-more) can leave the server data stale — if it does, add `onClick={() => router.refresh()}` to those links (the `<Link>` stays the no-JS baseline).
+
+Build the actual `BrowserContent` controls from the React reference patterns, including its filter-group dispatch: `PRICE_RANGE` uses min/max inputs, while `LIST` and `BOOLEAN` use checkboxes. Checkbox names/values come from parsing `FilterValue.input` and passing that exact parsed filter through `serializeCollectionParams(...)`. Uncontrolled checkbox reset keys belong on the filter subtree keyed by serialized **filter state** (`serializeCollectionParams({filters: state.filters, sortKey: undefined, reverse: false}).toString()`), not the live URL — the URL clears before the `CollectionProvider` reconciler settles `state.filters`, so a URL-keyed remount bakes in stale `defaultChecked`.
+
+```tsx
+function filterValueInputParamEntries(input: string): Array<{ name: string; value: string }> {
+  let filter: ProductFilter;
+  try {
+    filter = JSON.parse(input) as ProductFilter;
+  } catch {
+    return [];
+  }
+
+  return Array.from(
+    serializeCollectionParams({ filters: [filter], sortKey: undefined, reverse: false }),
+    ([name, value]) => ({ name, value }),
+  );
+}
+```
+
+This helper is only an adapter from Storefront API `FilterValue.input` to Hydrogen's serializer. Do not replace it with an app-owned filter mapping table.
+
+## Search Pages
+
+Use the same component with a discriminated `mode`:
+
+```tsx
+const handle = props.mode === "collection" ? props.handle : `search:${props.term}`;
+```
+
+For search forms:
+
+- Render a separate search form with `name="q"`.
+- Inside the filter/sort form, include `<input type="hidden" name="q" value={term} />`.
+- Use `SEARCH_SORT_OPTIONS` with `RELEVANCE` and `PRICE`; do not offer collection-only sorts.
+
+## Links And Clear URLs
+
+Use `next/link` for clear links and active filter chips. If a removal URL is `"?"`, link to the base pathname. For search pages, preserve `q` when removing filters.
+
+## Gotchas
+
+- Components that call `useSearchParams()` must be client components.
+- Do not build browse links through Next route objects if filter param names contain dots. Use the serialized search string from Hydrogen.
+- If a page mixes static data and request-scoped private clients, mark the route dynamic deliberately rather than accidentally calling `headers()` deep inside a helper.

package/skills/hydrogen-collection-browser/references/nuxt.md

@@ -0,0 +1,108 @@
+# Nuxt
+
+Use the Vue binding from `@shopify/hydrogen/vue`. In Nuxt, route query objects can treat dotted keys as nested data, so use Hydrogen's serialized search string for navigation.
+
+## Local Re-Export
+
+Create a small storefront module:
+
+```ts
+// storefront/collection.ts
+export {
+  CollectionProvider,
+  useCollection,
+  useCollectionActions,
+  useCollectionForm,
+} from "@shopify/hydrogen/vue";
+```
+
+## Page Data
+
+Use `useAsyncData` or route-level server data to query the Storefront API with `parseCollectionParams(new URLSearchParams(search))`. Return:
+
+- `handle`
+- `dataSearch`
+- `products`
+- `availableFilters`
+- For search, `term` and `totalCount`
+
+Keep a way to refresh data after hydrated navigation, usually the `refresh` function returned by `useAsyncData`.
+
+## Provider Wrapper
+
+Nuxt can lag for one tick after `navigateTo`, so pin the target URL search while navigation and refresh are in flight:
+
+```vue
+<script setup lang="ts">
+import { normalizeCollectionSearch } from "@shopify/hydrogen";
+import { CollectionProvider } from "~/storefront/collection";
+
+const route = useRoute();
+const urlSearchOverride = ref<string | null>(null);
+const urlSearch = computed(() => urlSearchOverride.value ?? collectionRouteSearch(route));
+const collectionData = computed(() => ({
+  handle: props.handle,
+  dataSearch: props.dataSearch,
+}));
+
+async function handleChange(search: string) {
+  const normalizedSearch = normalizeCollectionSearch(search);
+  props.setQueryWatchSuppressed(true);
+  urlSearchOverride.value = normalizedSearch;
+  try {
+    await navigateTo(`${route.path}${search}`, { replace: urlSearch.value.length > 0 });
+    await props.refreshCollection(search);
+  } finally {
+    urlSearchOverride.value = null;
+    props.setQueryWatchSuppressed(false);
+  }
+}
+</script>
+
+<template>
+  <CollectionProvider :data="collectionData" :url-search="urlSearch" @change="handleChange">
+    <CollectionBrowserContent />
+  </CollectionProvider>
+</template>
+```
+
+`collectionRouteSearch(route)` should return the current URL search string with literal dotted keys. Do not rely on `route.query` for filter serialization.
+
+## Browse Content
+
+In the content component:
+
+```vue
+<script setup lang="ts">
+import {
+  getFilterRemovalUrl,
+  getSortByValue,
+  isFilterInputActive,
+  serializeCollectionParams,
+} from "@shopify/hydrogen";
+import { useCollection, useCollectionForm } from "~/storefront/collection";
+
+const state = useCollection();
+const { formProps } = useCollectionForm();
+const fProps = formProps();
+const isLoading = computed(() => state.value.status === "loading");
+</script>
+
+<template>
+  <form v-bind="fProps" method="get" :action="collectionPath">
+    <!-- filters, sort, product grid -->
+  </form>
+</template>
+```
+
+Apply form helper props with `v-bind`. Branch on `filter.type`: render min/max number inputs for `PRICE_RANGE`, and value checkboxes for `LIST` and `BOOLEAN`. Submit price inputs on blur only when the value changed; let Enter blur the input.
+
+## Search Pages
+
+Use `handle = computed(() => \`search:${term.value}\`)` for provider data. Include a hidden `q` input inside the filter/sort form. When the term changes, suppress stale query watchers while refreshing data.
+
+## Gotchas
+
+- Browser-side Storefront API refetches should use the same-origin SFAPI proxy, not the remote store domain. Use the `hydrogen-storefront-client` skill for the same-origin SFAPI proxy setup.
+- Preserve unrelated query params when removing filters.
+- If loading never settles, verify `dataSearch` and `urlSearch` normalize to the same string.

package/skills/hydrogen-collection-browser/references/react.md

@@ -0,0 +1,301 @@
+# React And React Router
+
+## Contents
+
+- Loader
+- Provider
+- Browse Form
+- Filters
+- Search Pages
+
+Use the React binding:
+
+```tsx
+import {
+  getFilterRemovalUrl,
+  getSortByValue,
+  isFilterInputActive,
+  parseCollectionParams,
+  serializeCollectionParams,
+  type AvailableFilter,
+  type CollectionState,
+  type ProductFilter,
+} from "@shopify/hydrogen";
+import { CollectionProvider, useCollection, useCollectionForm } from "@shopify/hydrogen/react";
+import type { ProductFilter as StorefrontApiProductFilter } from "@shopify/hydrogen/storefront-api-types";
+```
+
+Use `getSortByValue(...)` for option values so the `sort_by` query param round-trips through `parseCollectionParams()`:
+
+```ts
+const COLLECTION_SORT_OPTIONS = [
+  { label: "Featured", value: getSortByValue("COLLECTION_DEFAULT", false) },
+  { label: "Best selling", value: getSortByValue("BEST_SELLING", false) },
+  { label: "Alphabetically, A-Z", value: getSortByValue("TITLE", false) },
+  { label: "Alphabetically, Z-A", value: getSortByValue("TITLE", true) },
+  { label: "Price, low to high", value: getSortByValue("PRICE", false) },
+  { label: "Price, high to low", value: getSortByValue("PRICE", true) },
+  { label: "Date, old to new", value: getSortByValue("CREATED", false) },
+  { label: "Date, new to old", value: getSortByValue("CREATED", true) },
+];
+
+const SEARCH_SORT_OPTIONS = [
+  { label: "Relevance", value: getSortByValue("RELEVANCE", false) },
+  { label: "Price, low to high", value: getSortByValue("PRICE", false) },
+  { label: "Price, high to low", value: getSortByValue("PRICE", true) },
+];
+```
+
+## Loader
+
+In a route loader, parse the current URL and query the Storefront API with the parsed browse state:
+
+```ts
+export async function loader({ context, params, request }: Route.LoaderArgs) {
+  const storefrontClient = context.get(storefrontClientContext);
+  const url = new URL(request.url);
+  const browse = parseCollectionParams(url.searchParams);
+
+  const { data } = await storefrontClient.graphql(COLLECTION_QUERY, {
+    variables: {
+      handle: params.handle,
+      first: 24,
+      filters:
+        browse.filters.length > 0 ? (browse.filters as StorefrontApiProductFilter[]) : undefined,
+      sortKey: browse.sortKey,
+      reverse: browse.reverse || undefined,
+    },
+  });
+
+  if (!data?.collection) throw new Response("Collection not found", { status: 404 });
+
+  return {
+    collection: data.collection,
+    products: data.collection.products.nodes,
+    availableFilters: data.collection.products.filters,
+    dataSearch: url.searchParams.toString(),
+  };
+}
+```
+
+Keep `dataSearch` exactly aligned with the query used for the server data.
+
+## Provider
+
+Wrap the browse UI in `CollectionProvider` and let it own filter/sort intent:
+
+```tsx
+export default function CollectionRoute({ loaderData }: Route.ComponentProps) {
+  const navigate = useNavigate();
+  const [searchParams] = useSearchParams();
+
+  return (
+    <CollectionProvider
+      data={{ handle: loaderData.collection.handle, dataSearch: loaderData.dataSearch }}
+      urlSearch={searchParams.toString()}
+      onChange={(search) =>
+        navigate(
+          { search },
+          {
+            replace: searchParams.size > 0,
+            preventScrollReset: true,
+          },
+        )
+      }
+    >
+      <CollectionPage {...loaderData} />
+    </CollectionProvider>
+  );
+}
+```
+
+## Browse Form
+
+Inside the browse UI:
+
+```tsx
+function CollectionPage({ availableFilters, products }: Props) {
+  const state = useCollection();
+  const { formProps } = useCollectionForm();
+  const isLoading = state.status === "loading";
+
+  return (
+    <form {...formProps()} method="get" action={collectionPath} className="browse">
+      <FilterSidebar
+        availableFilters={availableFilters}
+        activeFilters={state.filters}
+        disabled={isLoading}
+      />
+      <select name="sort_by" defaultValue={currentSortValue(state)} onChange={requestFormSubmit}>
+        {COLLECTION_SORT_OPTIONS.map((option) => (
+          <option key={option.label} value={option.value}>
+            {option.label}
+          </option>
+        ))}
+      </select>
+      <ProductGrid products={products} pending={isLoading} />
+    </form>
+  );
+}
+
+function requestFormSubmit(event: React.ChangeEvent<HTMLInputElement | HTMLSelectElement>) {
+  event.currentTarget.form?.requestSubmit();
+}
+```
+
+Pass `method="get"` and an explicit `action={collectionPath}` (the current `/collections/:handle` or `/search` route URL) literally — `formProps()` only wires the submit handler (see the SKILL.md UI rule).
+
+Use uncontrolled form controls. When a route needs to remount them after external navigation, put `key={serializeCollectionParams({ filters: state.filters, sortKey: undefined, reverse: false }).toString()}` on the filter subtree (for search, include the term in the key) — keyed by serialized **filter state**, not the live URL. The URL clears before the `CollectionProvider` reconciler settles `state.filters`, so a URL-keyed remount bakes in stale defaults. This resets checkbox and price-input DOM state without coupling active filter chips to the form remount.
+
+## Filters
+
+Choose the control at the filter-group level. `PRICE_RANGE` uses min/max number inputs; `LIST` and `BOOLEAN` use checkboxes. Do not use the number of serialized entries to choose the control—a price value serializes to both `gte` and `lte`.
+
+```tsx
+function FilterGroup({
+  activeFilters,
+  filter,
+}: {
+  activeFilters: ProductFilter[];
+  filter: AvailableFilter;
+}) {
+  if (filter.type === "PRICE_RANGE") {
+    return <PriceRangeInput activeFilters={activeFilters} />;
+  }
+
+  return filter.values.map((value) => (
+    <CheckboxFilterValue
+      key={value.id}
+      activeFilters={activeFilters}
+      filter={filter}
+      value={value}
+    />
+  ));
+}
+
+function PriceRangeInput({ activeFilters }: { activeFilters: ProductFilter[] }) {
+  const price = activeFilters.find((filter) => filter.price)?.price;
+  return (
+    <>
+      <PriceInput name="filter.v.price.gte" defaultValue={price?.min} label="Minimum price" />
+      <PriceInput name="filter.v.price.lte" defaultValue={price?.max} label="Maximum price" />
+    </>
+  );
+}
+
+function PriceInput({ name, defaultValue, label }: { name: string; defaultValue?: number; label: string }) {
+  const initialValue = defaultValue == null ? "" : String(defaultValue);
+  return (
+    <input
+      type="number"
+      name={name}
+      defaultValue={defaultValue}
+      aria-label={label}
+      min="0"
+      step="any"
+      onBlur={(event) => {
+        if (event.currentTarget.value !== initialValue) {
+          event.currentTarget.form?.requestSubmit();
+        }
+      }}
+      onKeyDown={(event) => {
+        if (event.key === "Enter") {
+          event.preventDefault();
+          event.currentTarget.blur();
+        }
+      }}
+    />
+  );
+}
+
+function filterValueInputParamEntries(input: string): Array<{ name: string; value: string }> {
+  let filter: ProductFilter;
+  try {
+    filter = JSON.parse(input) as ProductFilter;
+  } catch {
+    return [];
+  }
+
+  return Array.from(
+    serializeCollectionParams({ filters: [filter], sortKey: undefined, reverse: false }),
+    ([name, value]) => ({ name, value }),
+  );
+}
+
+function CheckboxFilterValue({
+  activeFilters,
+  filter,
+  value,
+}: {
+  activeFilters: ProductFilter[];
+  filter: AvailableFilter;
+  value: AvailableFilter["values"][number];
+}) {
+  const entries = filterValueInputParamEntries(value.input);
+  if (entries.length !== 1) return null;
+
+  const [{ name, value: paramValue }] = entries;
+
+  return (
+    <input
+      type="checkbox"
+      name={name}
+      value={paramValue}
+      defaultChecked={isFilterInputActive(activeFilters, value.input)}
+      onChange={(event) => {
+        if (isMutuallyExclusive(filter) && event.currentTarget.checked) {
+          uncheckSiblings(event.currentTarget);
+        }
+        requestFormSubmit(event);
+      }}
+    />
+  );
+}
+```
+
+Use `filter.type` only to choose the control shape. For checkbox values, keep `filterValueInputParamEntries` as thin app glue: `JSON.parse(value.input)` plus `serializeCollectionParams(...)`. Do not derive checkbox params from IDs, labels, or filter types.
+
+For active chips, use parsed active `ProductFilter` values from collection state:
+
+```tsx
+function ActiveFilterChip({ collectionPath, filter, state }: Props) {
+  const currentParams = serializeCollectionParams(state);
+  const removal = getFilterRemovalUrl(currentParams, filter);
+  const href = removal === "?" ? collectionPath : `${collectionPath}${removal}`;
+
+  return (
+    <a href={href}>
+      {describeFilter(filter)}
+    </a>
+  );
+}
+```
+
+When passing `browse.filters` into a `gql()` query variable typed from Storefront API introspection, match the app's established pattern. The Hydrogen examples cast the parsed filters to the generated Storefront API `ProductFilter` type at the query variable boundary:
+
+```ts
+import type { ProductFilter as StorefrontApiProductFilter } from "@shopify/hydrogen/storefront-api-types";
+
+variables: {
+  filters:
+    browse.filters.length > 0 ? (browse.filters as StorefrontApiProductFilter[]) : undefined,
+}
+```
+
+Keep this as a generated-type cast scoped to the query variable boundary.
+
+## Search Pages
+
+Use the same binding with a synthetic handle:
+
+```tsx
+<CollectionProvider
+  data={{ handle: `search:${term}`, dataSearch }}
+  urlSearch={searchParams.toString()}
+  onChange={(search) => navigate({ search }, { replace: searchParams.size > 0 })}
+>
+  <input type="hidden" name="q" value={term} />
+</CollectionProvider>
+```
+
+When the search term changes, include it in the browse form `key` so old unchecked/checked inputs do not carry over.