Add search and filters

Outcome: a Storefront product search that sends one query expression, preserves filter state in the URL, and paginates within a stable commerce context.

Prerequisites

Start from Build product listing and detail pages. Read the query argument’s generated filter table on the products reference; it is owned by the public API and is the source for supported filter names and examples.

1. Build one expression

GraphQL

Code in graphql

For the lamp fixture, start with lighting AND available_for_sale:true. Add only fields listed for this exact query argument. Resource query filters are not cart or product discount predicates; they use different evaluators and contexts.

2. Preserve state

Store the text term, selected filters, and sort in URL parameters. Rebuild the query expression from validated UI state. When any filter, sort, or commerce-context value changes, clear the cursor and restart from the first page.

Escape user-entered phrases according to Search query language. Never splice an unchecked field name from the browser into the expression.

3. Verify

Test a matching term, a quoted phrase, one documented field filter, a combined filter, an empty result, and at least two cursor pages. Confirm that refreshing the browser reproduces the same filter state and context.

Add discovery counts with Configure and render facets.