Storefront search

Storefront search is based on query parameters that determine what information is returned, and how it’s returned, in the search results. In addition to the search query itself, there are parameters that allow you to customize the search in the following ways:

  • Only search for certain resource types
  • Choose whether unavailable products are returned, and where in the results
  • Enable partial word matches

The query parameters can be used by including inputs in your search form, and they’re reflected in the search URL when a search is performed.

Query parameters

Search queries accept the following parameters:

Query parameter Type Required Description
q String Yes The search query.
type Comma-separated values No

Specifies the type of results requested. The possible options are:

  • product
  • page
  • article

Defaults to all types.

page Integer No Specifies the current search results page. Defaults to 1.
options Hash No Specifies search options that you can customize with the unavailable_products and prefix settings.
unavailable_products String No

Specifies whether to display results for unavailable products. The possible options are:

  • show - Show unavailable products in the order that they're found.
  • hide - Exclude unavailable products.
  • last - Show unavailable products after all other matching results. This is the default.
prefix Comma-separated values No

Specifies whether we want to perform a partial word match on the last search term.

For example, if "winter snow" is used as a search query, a search will find all applicable resources that contain both "winter" and any term that starts with "snow". This could be terms like "snow", "snowshoe", or "snowboard".

The possible options are:

  • none - Do not perform a partial word match on the last search term. This is the default.
  • last - Perform a partial word match on the last search term.
sort_by String No

Specifies the sort order of the results. The possible options are:

  • relevance - Sort results by relevance to the search query.
  • price-ascending - Sort results by price from high to low. All non-product results are pushed to the end of the results array.
  • price-descending - Sort results by price from low to high. All non-product results are pushed to the end of the results array.

Defaults to relevance.

The search form

The search form can be included with a <form> element that has an attribute of action="/search". Inside the form, you can include inputs for each of the query parameters above, where each input has the following attributes:

  • name="query-parameter"
  • value="parameter-value"

Aside from the q parameter, none of the query parameters require user input, so should be hidden inputs.

For example:

Search URL structure

When a search is performed, the search page’s URL is updated to reflect that. The general format is:

For example: