Collection URL parameters
The collection URL parameter functions read collection filters and sort from the URL and write them back, with the same parameter names that Liquid themes use. Use the functions to read filters and sort in a loader, name filter form fields, and build sort options.
Import parseCollectionParams, serializeCollectionParams, normalizeCollectionSearch, getSortByValue, and parseSortByValue from @shopify/hydrogen.
Anchor to Parameter parsingParameter parsing
Reads collection filters and sort from URL search params. Pass the result to your Storefront API collection query.
The function reads Liquid-compatible filter.p.* and filter.v.* keys and the param.
A URL that sets availability to both in stock and out of stock produces no availability filter. The function recognizes the best-selling and manual sort values, plus created, price, and title with an ascending or descending suffix. For other sort values, the sort key is undefined. The function also recognizes relevance, collection default, and ID.
- Anchor to searchParamssearch
Paramssearch Params URLSearchParamsURLSearchParamsrequiredrequired URL search params to read.
The filters, sort key, and sort direction from the URL.
CollectionParams
The filters, sort key, and sort direction in a collection URL.
- filters
Active product filters from the `filter.*` URL params. The filters use the Storefront Standard Events filter type. When your query variables use generated Storefront API types, cast the filters to the generated filter type where you pass them as variables.
ProductFilter[] - reverse
`true` when the `sort_by` value ends with `-descending`.
boolean - sortKey
Storefront API sort key from the `sort_by` param, or `undefined` when the param is missing or unrecognized.
ProductCollectionSortKeys | undefined
TypeScript
Examples
Description
Parse filters and sort from the request URL and pass them to a Storefront API collection query.
TypeScript
import { parseCollectionParams } from "@shopify/hydrogen"; declare const storefrontClient: { graphql(query: string, options: { variables: Record<string, unknown> }): Promise<unknown>; }; declare const COLLECTION_QUERY: string; export async function loader({ request, params }: { request: Request; params: { handle: string } }) { 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 : undefined, sortKey: browse.sortKey, reverse: browse.reverse || undefined, }, }); return { data, dataSearch: url.searchParams.toString() }; }
Anchor to Parameter serializationParameter serialization
Converts collection filters and sort to URL search params with Liquid-compatible keys. Use the result to build collection URLs.
The result holds only the filter.* and keys. The function leaves out for the collection's default sort.
Category filters convert to filter.p.category, which doesn't read. A price filter with a minimum and a maximum produces two params. To build a filter checkbox, parse a filter value's input string and convert the parsed filter. The resulting entries give the checkbox name and value.
- Anchor to statestatestatePick<CollectionState, "reverse" | "filters" | "sortKey">Pick<CollectionState, "reverse" | "filters" | "sortKey">requiredrequired
The filters, sort key, and sort direction to convert.
URL search params that hold the filters and sort.
CollectionState
The customer's filter and sort choices and the loading status. Products, product counts, available filters, and the collection ID come from your loader data.
- filters
Active product filters, matching the `filter.*` URL params.
ProductFilter[] - handle
Collection handle, such as `shoes`.
string - reverse
`true` for a descending sort. The URL's sort value then ends in `-descending`.
boolean - sortKey
Storefront API sort key, or `undefined` for the collection's default sort.
ProductCollectionSortKeys | undefined - status
Reads `loading` from a filter or sort change until the store settles, and `idle` when the results match the filters and sort. Show a loading state while the value is `loading`.
'idle' | 'loading'
TypeScript
Examples
Description
Turn a Storefront API filter input JSON string into form field entries.
TypeScript
import { serializeCollectionParams, type ProductFilter } from "@shopify/hydrogen"; export function filterValueInputParamEntries(input: 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 }), ); }
Anchor to Search string normalizationSearch string normalization
Removes a leading ? from a search string. Normalize search strings before you compare them.
- Anchor to searchsearchsearchstringstringrequiredrequired
The search string from your router, with or without a leading
?.
Anchor to normalizeCollectionSearch-returnsReturnsstringstring
The search string without a leading
?.
TypeScript
Examples
Description
Update a collection store from the URL. This example normalizes the router and loader search strings and settles the store when the two strings match.
TypeScript
import { normalizeCollectionSearch, type CollectionStore } from "@shopify/hydrogen"; export function syncStore(store: CollectionStore, urlSearch: string, dataSearch: string) { const normalizedUrlSearch = normalizeCollectionSearch(urlSearch); const params = new URLSearchParams(normalizedUrlSearch); if (!store.matchesParams(params)) { store.syncFromParams(params); } if (normalizeCollectionSearch(dataSearch) === normalizedUrlSearch) { store.settle(); } }
Anchor to Sort valuesSort values
Converts a Storefront API sort key and direction to a Liquid-compatible value, such as price-ascending or best-selling.
Only the price, title, created, and ID sort keys get a direction suffix. Other sort keys, such as best selling, ignore the direction.
Anchor to getSortByValue-parametersParameters
- Anchor to sortKeysort
Keysort Key ProductCollectionSortKeysProductCollectionSortKeysrequiredrequired Storefront API product collection sort key.
- Anchor to reversereversereversebooleanbooleanrequiredrequired
truefor descending,falsefor ascending.
Anchor to getSortByValue-returnsReturnsstringstring
The value for the
URL param.
Converts a Liquid-compatible value to a Storefront API sort key and direction. The function does the opposite conversion.
For unrecognized values, the sort key is undefined.
Anchor to parseSortByValue-parametersParameters
- Anchor to valuevaluevaluestringstringrequiredrequired
A
value, such asprice-ascendingorbest-selling.
The sort key and
reverse, which readstruefor descending values.
TypeScript
Examples
Description
Create labeled sort options for a collection sort select.
TypeScript
import { getSortByValue } from "@shopify/hydrogen"; export const COLLECTION_SORT_OPTIONS = [ { label: "Featured", value: "" }, { 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) }, ];