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.

<div class="resource-card-grid">
  <div>
  <a class="resource-card" href="/docs/storefronts/themes/navigation-search/filtering/storefront-filtering/support-storefront-filtering" data-theme-mode="">
    <div class="resource-card__indicator-container"><img
     src="/assets/resource-cards/docs"
     data-alt-src="/assets/resource-cards/docs-dark"
     aria-hidden="true"
     class="resource-card__icon themed-image"></div>
    <h3 class="resource-card__title">
      Support storefront filtering
    </h3>
    <p class="resource-card__description">Learn more about how to support storefront filtering in your theme.</p>
  </a>
</div></p>

<p><div>
  <a class="resource-card" href="/docs/storefronts/themes/navigation-search/filtering/storefront-filtering/storefront-filtering-ux" data-theme-mode="">
    <div class="resource-card__indicator-container"><img
     src="/assets/resource-cards/theme"
     data-alt-src="/assets/resource-cards/theme-dark"
     aria-hidden="true"
     class="resource-card__icon themed-image"></div>
    <h3 class="resource-card__title">
      Storefront filtering UX
    </h3>
    <p class="resource-card__description">Familiarize yourself with UX considerations for storefront filtering.</p>
  </a>
</div>
</div>


## 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:

<table>
  <thead>
    <tr>
      <th>Component</th>
      <th>Required</th>
      <th>Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><code>filter</code></td>
      <td>Yes</td>
      <td>The default namespace for filter URL parameters.</td>
    </tr>
    <tr>
      <td><code>filter_scope</code></td>
      <td>Yes</td>
      <td>
        <p>The scope of the filter. Can be either of the following:<p>
        <ul>
          <li><code>p</code> - To note that the scope is on the product level.</li>
          <li><code>v</code> - To note that the scope is on the variant level.</li>
        </ul>
      </td>
    </tr>
    <tr>
      <td><code>attribute</code></td>
      <td>Yes</td>
      <td>The attribute the filter is based on. To learn more about the available attributes, refer to <a href="#filter-types">Filter types</a>.</td>
    </tr>
    <tr>
      <td><code>attribute_scope</code></td>
      <td>No</td>
      <td>The attribute scope for <code>option</code> and <code>price</code> attributes. To learn more, refer to <a href="#variant-specific-filters">Variant-specific filters</a></td>
    </tr>
    <tr>
      <td><code>value</code></td>
      <td>Yes</td>
      <td>The filter value. To learn more about the value format, refer to <a href="#filter-types">Filter types</a>.</td>
    </tr>
  </tbody>
</table>

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

<p>
<div class="react-code-block" data-preset="file">
<div class="react-code-block-preload ThemeMode-dim">
<div class="react-code-block-preload-bar "></div>
<div class="react-code-block-preload-placeholder-container">
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>

</div>
</div>

<script data-option="filename" data-value="Example"></script>

<script type="text/plain" data-language="text">
RAW_MD_CONTENTfilter.v.option.color=red,blue
filter.v.option.color=red&filter.v.option.color=blue
END_RAW_MD_CONTENT</script>

</div>
</p>


### 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):

<table>
  <thead>
    <tr>
      <th>Name</th>
      <th>Description</th>
      <th>Parameter name</th>
      <th>Accepted parameter value</th>
    </tr>
  </thead>
  <tbody>
    <tr>
    <td>Category</td>
      <td>Filter based on specific product categories.</td>
      <td><code>t.category</code></td>
      <td>
        <p>A single category ID or a <code>__</code> separated list of category ids </p>
        <p>For example ,<code>aa-1</code>, or <code>aa-1__aa-2</code>.</p>
      </td>
    </tr>
    <tr>
      <td>Product tags</td>
      <td>Filter based on specific product tags.</td>
      <td><code>tag</code></td>
      <td>
        <p>A single product tag, or a comma-separated list of product tags.</p>
        <p>For example <code>new</code>, or <code>new,trending</code>.</p>
      </td>
    </tr>
    <tr>
      <td>Product type</td>
      <td>Filter based on specific product types.</td>
      <td><code>product_type</code></td>
      <td>
        <p>A single product type, or a comma-separated list of product types.</p>
        <p>For example <code>shoes</code>, or <code>shoes,belts</code>.</p>
      </td>
    </tr>
    <tr>
      <td>Vendor</td>
      <td>Filter based on specific vendors.</td>
      <td><code>vendor</code></td>
      <td>
        <p>A single vendor, or a comma-separated list of vendors.</p>
        <p>For example <code>vendor1</code>, or <code>vendor1,vendor2</code>.</p>
      </td>
    </tr>
    <tr>
      <td>Metafield</td>
      <td>
        <p>Filter based on a specific product metafield.</p>
        <p>Metafield-based filters can reference metafields of the following types:</p>
<ul>
  <li><code>single_line_text_field</code></li>
  <li><code>list.single_line_text_field</code></li>
  <li><code>metaobject_reference</code></li>
  <li><code>list.metaobject_reference</code></li>
  <li><code>number_integer</code></li>
  <li><code>number_decimal</code></li>
  <li><code>boolean</code></li>
</ul>

        <p>Metafield-based filters also need to specify the metafield namespace and key for the <code>attribute_scope</code> component of the <a href="#url-parameter-structure">URL parameter structure</a>.</p>

        <p>For example, if your metafield has a namespace of <code>custom</code> and key of <code>made_in</code>, then the structure would look like the following:</p>
        <p><code>m.custom.made_in</code></p>
      </td>
      <td><code>m</code></td>
      <td>
        <p>A single metafield value, or a comma-separated list of metafield values.</p>
        <p>For example, <code>canada</code> or <code>canada,usa</code>.</p>
        <p><strong>Note:</strong> 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.</p>
      </td>
    </tr>
  </tbody>
</table>

> 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):

<table>
  <thead>
    <tr>
      <th>Name</th>
      <th>Description</th>
      <th>Parameter name</th>
      <th>Accepted parameter value</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Availability</td>
      <td>Filter based on variant availability.</td>
      <td><code>availability</code></td>
      <td>
        <p>Either of the following:</p>
        <ul>
          <li><code>0</code> - Variants that are out of stock.</li>
          <li><code>1</code> - Variants that are in stock.</li>
          <li><code>0,1</code> - Variants of either stock status.</li>
        </ul>
      </td>
    </tr>
    <tr>
      <td>Variant option</td>
      <td>
        <p>Filter based on a variant option, such as <strong>Size</strong> or <strong>Color</strong>.</p>
        <p>Variant option filters also need to specify the option name for the <code>attribute_scope</code> component of the <a href="#url-parameter-structure">URL parameter structure</a>.</p>
        <p>For example, <code>option.color</code>.</p>
      </td>
      <td><code>option</code></td>
      <td>
        <p>A single variant option value, or a comma-separated list of variant option values.</p>
        <p>For example <code>red</code>, or <code>red,blue</code>.</p>
      </td>
    </tr>
    <tr>
      <td>Price</td>
      <td>
        <p>Filter based on variant price.</p>
        <p>Price filters also need to specify the price condition for the <code>attribute_scope</code> component of the <a href="#url-parameter-structure">URL parameter structure</a>. The following are the accepted values:</p>
        <ul>
          <li><code>lte</code> - Based on prices less than, or equal to, the entered value.</li>
          <li><code>gte</code> - Based on prices greater than, or equal to, the entered value.</li>
        </ul>
      </td>
      <td><code>price</code></td>
      <td>
        <p>A single monetary value in the format of the shop's default currency.</p>
        <p>For example <code>5</code> or <code>20.40</code>.</p>
      </td>
    </tr>
    <tr>
      <td>Standard product attribute</td>
      <td>
        <p>Filter based on a product metafield generated for a standard product attribute that can be connected to product options.</p>
        <p>Standard product attribute metafield-based filters reference standard metafields of type <code>list.metaobject_reference</code>.</p>
        <p>Standard product attribute metafield-based filters also need to specify the <code>shopify</code> namespace and key for the <code>attribute_scope</code> component of the <a href="#url-parameter-structure">URL parameter structure</a>.</p>
        <p>For example, if your standard product attribute metafield has the key <code>fabric</code>, then the structure would look like <code>t.shopify.fabric</code></p>
      </td>
      <td><code>t</code></td>
      <td>
        <p>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</p>
        <p>For example, <code>gid://shopify/Metaobject/1</code> or <code>gid://shopify/Metaobject/1, gid://shopify/Metaobject/3</code>.</p>
      </td>
    </tr>
    <tr>
      <td>Metafield</td>
      <td>
        <p>Filter based on a specific variant metafield.</p>
        <p>Metafield-based filters can reference metafields of the following types:</p>
<ul>
  <li><code>single_line_text_field</code></li>
  <li><code>list.single_line_text_field</code></li>
  <li><code>metaobject_reference</code></li>
  <li><code>list.metaobject_reference</code></li>
  <li><code>number_integer</code></li>
  <li><code>number_decimal</code></li>
  <li><code>boolean</code></li>
</ul>

        <p>Metafield-based filters also need to specify the metafield namespace and key for the <code>attribute_scope</code> component of the <a href="#url-parameter-structure">URL parameter structure</a>.</p>

        <p>For example, if your metafield has a namespace of <code>custom</code> and key of <code>fabric</code>, then the structure would look like the following:</p>
        <p><code>m.custom.fabric</code></p>
      </td>
      <td><code>m</code></td>
      <td>
        <p>A single metafield value, or a comma-separated list of metafield values.</p>
        <p>For example, <code>leather</code> or <code>leather,suede</code>.</p>
        <p><strong>Note:</strong> 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.</p>
      </td>
    </tr>
  </tbody>
</table>

> 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](/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](/docs/storefronts/themes/product-merchandising/variants#variant-deep-link-handling) the first matching variant.