Storefront filtering

Storefront filtering allows merchants to add filters to their collection and search results pages based on the following product and variant attributes:

  • Availability
  • Price
  • Product type
  • Vendor
  • Variant options
  • Metafields

Filters are applied with AND logic, and filter values with OR. For example, you can return products that are a specific color and a specific size, or you can return products that are one color or another.

There are two main components to supporting filters in your theme:

The filter display

The following sections outline a basic collection and search results filter implementation. For a more in-depth solution, refer to Dawn's implementation.

Collection filter display

Search results filter display

Filter URL parameters

Applied filters are reflected in the page URL with URL parameters based on the filter type. These URL parameters have a specific structure.

URL parameter structure

Filter URL parameters consist of the following components:

Component Required Description
filter Yes The default namespace for filter URL parameters.
filter_scope Yes

The scope of the filter. Can be either of the following:

  • p - To note that the scope is on the product level.
  • v - To note that the scope is on the variant level.
attribute Yes The attribute the filter is based on. To learn more about the available attributes, refer to Filter types.
attribute_scope No The atrribute scope for option and price attributes. To learn more, refer to Variant-specific filters
value Yes The filter value. To learn more about the value format, refer to Filter types.

The format of the URL parameter varies depending on the filter attribute, however can be one of the following:

For example, if you had the following filters:

  • A filter based on the shoes product type
  • A filter based on the Color variant option, with a value of red

Then the URL parameters for each would be the following:

Multiple filters

You can have multiple filters like the following:

You can also filter on multiple values from the same filter. This can be done in two ways:

  • Include multiple values in a single parameter
  • Include a parameter for each value

Filter types

Filters can be applied at two levels:

Product-specific filters

The following outlines the product-specific filters and how they're reflected as a URL parameter:

Name Description Parameter name Accepted value
Product type Filter based on specific product types. product_type

A single product type, or a comma-separated list.

For example shoes, or shoes,belts.

Vendor Filter based on specific vendors. vendor

A single vendor, or a comma-separated list.

For example vendor1, or vendor1,vendor2.

Metafield

Filter based on a specific variant metafield.

Metafield-based filters can reference metafields of the following types:

  • single_line_text_field
  • number_integer
  • number_decimal

Metafield-based filters also need to specify the metafield namespace and key for the attribute_scope component of the URL parameter structure.

For example, m.my_fields.made_in.

m

A single metafield value, or a comma-separated list.

For example, canada or canada,usa.

The following is an example of the full URL parameter structure for the product-specific filters:

Variant-specific filters

The following outlines the variant-specific filters and how they're reflected as a URL parameter:

Name Description Parameter name Accepted value
Availability Filter based on variant availability. availability

Either of the folowing:

  • 0 - Variants that are out of stock.
  • 1 - Variants that are in stock.
  • 0,1 - Variants of either stock status.
Variant option

Filter based on a variant option, such as Size or Color.

Variant option filters also need to specify the option name for the attribute_scope component of the URL parameter structure.

For example, option.color.

option

A single variant option value, or a comma-separated list.

For example red, or red,blue.

Price

Filter based on variant price.

Price filters also need to specify the price condition for the attribute_scope component of the URL parameter structure. The following are the accepted values:

  • lte - Based on prices less than, or equal to, the entered value.
  • gte - Based on prices greater than, or equal to, the entered value.
price

A single monetary value in the format of the shop's default currency.

For example 5 or 20.40.

Metafield

Filter based on a specific variant metafield.

Metafield-based filters can reference metafields of the following types:

  • single_line_text_field
  • number_integer
  • number_decimal

Metafield-based filters also need to specify the metafield namespace and key for the attribute_scope component of the URL parameter structure.

For example, m.my_fields.fabric.

m

A single metafield value, or a comma-separated list.

For example, leather or leather,suede.

The following is an example of the full URL parameter structure for the variant-specific filters: