Storefront filtering

Storefront filtering is the recommended method for filtering products in a theme. It allows merchants to easily create filters for filtering collection and search results pages.

Filters can be based on the following product and variant data:

Availability
Category
Price
Product tags
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.

When filters are applied, they're reflected in the collection or search URL through URL parameters.

Implementing storefront filtering

Anchor link to section titled "Implementing storefront filtering"

Use the following resources to learn how to implement storefront filtering in your theme.

Support storefront filtering

Learn more about how to support storefront filtering in your theme.

Storefront filtering UX

Familiarize yourself with UX considerations for storefront filtering.

Filter URL parameters

Anchor link to section titled "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

Anchor link to section titled "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 attribute 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.

Depending on the filter attribute, the format of the URL parameter 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:

If these filters were applied to the all collection, then the collection URL would be the following:

Multiple filters

Anchor link to section titled "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

Anchor link to section titled "Filter types"

Filters can be applied at two levels:

The product level
The variant level

Product-specific filters

Anchor link to section titled "Product-specific filters"

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

Name	Description	Parameter name	Accepted parameter value
Category	Filter based on specific product categories.	`t.category`	A single category ID or a `__` separated list of category ids For example ,`aa-1`, or `aa-1__aa-2`.
Product tags	Filter based on specific product tags.	`tag`	A single product tag, or a comma-separated list of product tags. For example `new`, or `new,trending`.
Product type	Filter based on specific product types.	`product_type`	A single product type, or a comma-separated list of product types. For example `shoes`, or `shoes,belts`.
Vendor	Filter based on specific vendors.	`vendor`	A single vendor, or a comma-separated list of vendors. For example `vendor1`, or `vendor1,vendor2`.
Metafield	Filter based on a specific product metafield. Metafield-based filters can reference metafields of the following types: `single_line_text_field` `list.single_line_text_field` `metaobject_reference` `list.metaobject_reference` `number_integer` `number_decimal` `boolean` Metafield-based filters also need to specify the metafield namespace and key for the `attribute_scope` component of the URL parameter structure. For example, if your metafield has a namespace of `custom` and key of `made_in`, then the structure would look like the following: `m.custom.made_in`	`m`	A single metafield value, or a comma-separated list of metafield values. For example, `canada` or `canada,usa`. Note: A comma-separated list of metafield values is a list of individual metafield values, not a single metafield value that contains a comma-separated list.

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

Variant-specific filters

Anchor link to section titled "Variant-specific filters"

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

Name	Description	Parameter name	Accepted parameter value
Availability	Filter based on variant availability.	`availability`	Either of the following: `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 of variant option values. 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`.
Category metafield	Filter based on category constrained product metafield that can be connected to product options. Category metafield-based filters reference standard metafields of type `list.metaobject_reference`. Category metafield-based filters also need to specify the `shopify` namespace and key for the `attribute_scope` component of the URL parameter structure. For example, if your category metafield has the key `fabric`, then the structure would look like `t.shopify.fabric`	`t`	A single metaobject GID, a comma-separated list of metaobject GIDs, a single taxonomy value GID, or a comma-separated list of taxonomy value GIDs For example, `gid://shopify/Metaobject/1` or `gid://shopify/Metaobject/1, gid://shopify/Metaobject/3`.
Metafield	Filter based on a specific variant metafield. Metafield-based filters can reference metafields of the following types: `single_line_text_field` `list.single_line_text_field` `metaobject_reference` `list.metaobject_reference` `number_integer` `number_decimal` `boolean` Metafield-based filters also need to specify the metafield namespace and key for the `attribute_scope` component of the URL parameter structure. For example, if your metafield has a namespace of `custom` and key of `fabric`, then the structure would look like the following: `m.custom.fabric`	`m`	A single metafield value, or a comma-separated list of metafield values. For example, `leather` or `leather,suede`. Note: A comma-separated list of metafield values is a list of individual metafield values, not a single metafield value that contains a comma-separated list.

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