Skip to main content

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.


Anchor to Implementing storefront filteringImplementing storefront filtering

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


Anchor to Filter URL parametersFilter 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.

Note

Before filters can be applied, they need to be created in the Shopify admin.

Anchor to URL parameter structureURL parameter structure

Filter URL parameters consist of the following components:

ComponentRequiredDescription
filterYesThe default namespace for filter URL parameters.
filter_scopeYes

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.
attributeYesThe attribute the filter is based on. To learn more about the available attributes, refer to Filter types.
attribute_scopeNoThe attribute scope for option and price attributes. To learn more, refer to Variant-specific filters
valueYesThe 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:

filter.filter_scope.attribute=value
filter.filter_scope.attribute.attribute_scope=value

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:

filter.p.product_type=shoes
filter.v.option.color=red

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

/collections/all?filter.p.product_type=shoes&filter.v.option.color=red

You can have multiple filters like the following:

filter.v.option.color=red&filter.v.option.size=L

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

Example

filter.v.option.color=red,blue
filter.v.option.color=red&filter.v.option.color=blue

Filters can be applied at two levels:

Anchor to Product-specific filtersProduct-specific filters

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

NameDescriptionParameter nameAccepted parameter value
CategoryFilter 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 tagsFilter 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 typeFilter 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.

VendorFilter 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.

Note

Users can create up to a maximum of 25 filters.

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

// Product tag
filter.p.tag=new,trending

// Product type
filter.p.product_type=shoes

// Product vendor
filter.p.vendor=vendor1

// Product metafield
filter.p.m.custom.made_in=canada

Anchor to Variant-specific filtersVariant-specific filters

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

NameDescriptionParameter nameAccepted parameter value
AvailabilityFilter 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.

Standard product attribute

Filter based on a product metafield generated for a standard product attribute that can be connected to product options.

Standard product attribute metafield-based filters reference standard metafields of type list.metaobject_reference.

Standard product attribute 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 standard product attribute 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.

Note

Users can create up to a maximum of 25 filters.

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

// Variant availability
filter.v.availability=1

// Variant price
filter.v.price.lte=5

// Variant option
filter.v.option.color=red

// Standard product attribute
filter.v.t.shopify.fabric=gid://shopify/Metaobject/1

// Variant metafields
filter.v.m.custom.fabric=leather
Tip

When variant-specific filters are applied, the featured_media and url attributes of the product object are updated to reflect the first variant that matches the current filters. The featured_media attribute returns the featured media of the first matching variant with media included, and the url attribute is updated to deep link the first matching variant.


Was this page helpful?