Collection filters
The collection filter functions help you build filter controls for a collection page. Use the functions to check the boxes for active filters, match a filter from the URL against a filter from the Storefront API, and build links that remove one filter.
Import filterEquals, isFilterInputActive, and getFilterRemovalUrl from @shopify/hydrogen.
Anchor to Filter matchingFilter matching
Checks whether two product filters match.
Price filters match when the minimum and maximum are equal, including ranges that set only one bound.
Anchor to filterEquals-parametersParameters
- ProductFilterProductFilterrequiredrequired
The first filter to compare.
- ProductFilterProductFilterrequiredrequired
The second filter to compare.
Anchor to filterEquals-returnsReturnsbooleanboolean
truewhen both filters are the same kind with the same values.falsefor different kinds or unrecognized filters.
TypeScript
Examples
Description
Match a price filter from the URL against a price filter in the Storefront API input format. This example also compares a tag filter with a vendor filter.
TypeScript
import { filterEquals, parseCollectionParams } from "@shopify/hydrogen"; const fromUrl = parseCollectionParams( new URLSearchParams("filter.v.price.gte=10&filter.v.price.lte=100"), ).filters[0]; const fromApi = { price: { min: 10, max: 100 } }; const samePrice = filterEquals(fromUrl, fromApi); const differentKind = filterEquals({ tag: "men" }, { productVendor: "Nike" });
Anchor to Active filtersActive filters
Checks whether a filter value's input JSON string from the Storefront API matches an active filter. Use the result to set the checked state of a filter control.
The function compares filters the same way as .
Anchor to isFilterInputActive-parametersParameters
- Anchor to activeFiltersactive
Filtersactive Filters ProductFilter[]ProductFilter[]requiredrequired The active filters, such as
filtersfrom the collection state.- Anchor to inputinputinputstringstringrequiredrequired
The filter value's
inputJSON string.
Anchor to isFilterInputActive-returnsReturnsbooleanboolean
truewhen the parsed input matches an active filter.falsewhen the input matches no active filter or isn't valid JSON.
Anchor to availablefilterAvailableFilter
A filter that the Storefront API returns for the current collection or search results. Render filter controls, such as checkboxes, swatches, and sliders, from the filter's values.
- Anchor to idididstringstringrequiredrequired
ID of the filter.
- Anchor to labellabellabelstringstringrequiredrequired
Name to display, such as "Color", "Size", or "Price".
- Anchor to typetypetypeFilterTypeFilterTyperequiredrequired
Kind of input, such as a boolean toggle, a multi-select list, or a price range.
- Anchor to valuesvaluesvaluesAvailableFilterValue<TValue>[]AvailableFilterValue<TValue>[]requiredrequired
Values that a customer can select, each with a label, a product count, and a filter input.
- Anchor to presentationpresentationpresentationFilterPresentation | nullFilterPresentation | null
How the storefront displays the filter's values. The Storefront API returns a value only for
LISTfilters andnullfor other filters.
FilterPresentation
How the storefront displays a filter's values.
"IMAGE" | "SWATCH" | "TEXT"FilterType
The kind of input a filter takes, such as a boolean toggle, a multi-select list, or a price range.
"BOOLEAN" | "LIST" | "PRICE_RANGE" | (string & {})AvailableFilterValue
A value that a customer can select within an available filter. Pass your Storefront API query's value type as `TValue` to include the `swatch` field when your query selects it.
BaseAvailableFilterValue & PickIfPresent<TValue, "swatch">BaseAvailableFilterValue
The ID, label, product count, and filter input that every filter value has.
- count
Number of products in the current results that match the value.
number - id
ID of the filter value.
string - input
Filter input as a JSON string. Pass the string to `toggleFilterInput()` or `isFilterInputActive`.
string - label
Label to display, such as "Red" or "Nike".
string
PickIfPresent
Copies a field from your query's value type when your query selects the field. Otherwise, the type adds no fields.
TKey extends keyof TValue
? Pick<TValue, TKey>
: {}TypeScript
Examples
Description
Compute the label, product count, and checked state for every available filter value.
TypeScript
import { isFilterInputActive, type AvailableFilter, type CollectionState } from "@shopify/hydrogen"; declare const state: CollectionState; declare const availableFilters: AvailableFilter[]; const checkboxes = availableFilters.flatMap((filter) => filter.values.map((value) => ({ label: value.label, count: value.count, checked: isFilterInputActive(state.filters, value.input), })), );
Anchor to Filter removal linksFilter removal links
Builds a query string from the current URL params, minus the given filter. Use the string in plain remove-filter links.
The function keeps every other param and drops the before and after pagination cursors, which sends the customer to the first page of results.
Anchor to getFilterRemovalUrl-parametersParameters
- Anchor to currentParamscurrent
Paramscurrent Params URLSearchParamsURLSearchParamsrequiredrequired The current URL search params.
- Anchor to filterfilterfilterProductFilterProductFilterrequiredrequired
The filter to remove from the URL.
Anchor to getFilterRemovalUrl-returnsReturnsstringstring
A query string that starts with
?. The string is?alone when no params remain.
TypeScript
Examples
Description
Build the link for an active filter chip. This example links to the collection path when no parameters remain.
TypeScript
import { getFilterRemovalUrl, serializeCollectionParams, type CollectionState, type ProductFilter, } from "@shopify/hydrogen"; export function filterRemovalHref( collectionPath: string, state: CollectionState, filter: ProductFilter, ) { const currentParams = serializeCollectionParams(state); const removal = getFilterRemovalUrl(currentParams, filter); return removal === "?" ? collectionPath : `${collectionPath}${removal}`; }