Skip to main content

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.

Tip

To learn more about storefront search functionality and search query options, refer to the Shopify Help Center.

You can also add predictive search to your theme so that suggested results appear immediately as you type into the search field. To learn about predictive search, refer to Add predictive search to your theme.

The Shopify Search & Discovery app enables users to customize product recommendation and search results, which can impact results from storefront search and the Ajax Product Recommendations API. To learn about how these results can be impacted, visit the Shopify Help Center.


Search queries accept the following parameters:

Query parameterTypeRequiredDescription
qStringYesThe search query.
typeComma-separated valuesNo

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

  • product
  • page
  • article

Defaults to all types.

To change the default value, you can use Search Settings in the Search & Discovery app.

pageIntegerNoSpecifies the current search results page. Defaults to 1.
optionsHashNoSpecifies search options that you can customize with the unavailable_products and prefix settings.
unavailable_productsStringNo

Specifies whether to display results for unavailable products or variants in filtered results. The following are the possible options:

  • show - Show unavailable products or variants in the order that they're found.
  • hide - Exclude unavailable products or variants.
  • last - Show unavailable products or variants after all other matching results.

Defaults to last.

To change the default value, you can use Search Settings in the Search & Discovery app.

prefixStringNo

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:

  • last - Perform a partial word match on the last search term. This is the default.
  • none - Don't perform a partial word match on the last search term.
sort_byStringNo

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 can be included with a <form> element that has an attribute of action="/search".

Tip

You should use the routes object to populate the action attribute so that the appropriate URL is used for multi-language stores.

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 they should be hidden inputs.

Example search form

<form action="{{ routes.search_url }}">
<input type="text"
placeholder="Search"
name="q"
value="{{ search.terms | escape }}"
/>
<input type="hidden" name="type" value="product,page" />
<input type="hidden" name="options[unavailable_products]" value="hide" />
<input type="hidden" name="options[prefix]" value="last" />
<input type="submit" value="Search" />
</form>
Tip

For another example of a search form, you can refer to Dawn's implementation.


Anchor to Search URL structureSearch URL structure

When a search is performed, the search page's URL is updated to reflect that.

For example, a search with the following parameters returns the following URL:

AttributeValue
qsnow
typeproduct,page
options[unavailable_products]hide
options[prefix]last
/search?q=snow&type=product,page&options[unavailable_products]=hide&options[prefix]=last

Was this page helpful?