---
title: Storefront filtering
description: About storefront filtering in themes.
source_url:
  html: >-
    https://shopify.dev/docs/storefronts/themes/navigation-search/filtering/storefront-filtering
  md: >-
    https://shopify.dev/docs/storefronts/themes/navigation-search/filtering/storefront-filtering.md
api_name: liquid
---

# Storefront filtering

Storefront filtering is the recommended method for filtering products in a theme. It allows merchants to [easily create filters](https://help.shopify.com/manual/online-store/themes/customizing-themes/storefront-filters#add-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](#filter-url-parameters).

***

## Implementing storefront filtering

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

[Support storefront filtering\
\
](https://shopify.dev/docs/storefronts/themes/navigation-search/filtering/storefront-filtering/support-storefront-filtering)

[Learn more about how to support storefront filtering in your theme.](https://shopify.dev/docs/storefronts/themes/navigation-search/filtering/storefront-filtering/support-storefront-filtering)

[Storefront filtering UX\
\
](https://shopify.dev/docs/storefronts/themes/navigation-search/filtering/storefront-filtering/storefront-filtering-ux)

[Familiarize yourself with UX considerations for storefront filtering.](https://shopify.dev/docs/storefronts/themes/navigation-search/filtering/storefront-filtering/storefront-filtering-ux)

***

## Filter URL parameters

Applied filters are reflected in the page URL with URL parameters based on the [filter type](#filter-types). These URL parameters have a [specific structure](#url-parameter-structure).

**Note:**

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

### 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](#filter-types). |
| `attribute_scope` | No | The attribute scope for `option` and `price` attributes. To learn more, refer to [Variant-specific filters](#variant-specific-filters) |
| `value` | Yes | The filter value. To learn more about the value format, refer to [Filter types](#filter-types). |

Depending on the filter `attribute`, the format of the URL parameter can be one of the following:

```text
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:

```text
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:

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

#### Multiple filters

You can have multiple filters like the following:

```text
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

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

### Filter types

Filters can be applied at two levels:

* [The product level](#product-specific-filters)
* [The variant level](#variant-specific-filters)

#### Product-specific filters

The following outlines the product-specific filters and how they're reflected as a [URL parameter](#filter-url-parameters):

| 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 idsFor 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](#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:

```text
// 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
```

#### Variant-specific filters

The following outlines the variant-specific filters and how they're reflected as a [URL parameter](#filter-url-parameters):

| 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](#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](#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](#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 GIDsFor 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](#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:

```text
// 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](https://shopify.dev/docs/api/liquid/objects/product) 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](https://shopify.dev/docs/storefronts/themes/product-merchandising/variants#variant-deep-link-handling) the first matching variant.

***