Storefront Filtering
Storefront filtering is the recommended way to filter products in a theme. It lets merchants easily create filters for search results and collection pages.
Filters can be based on the following product and variant data:
- Availability
- Product tags
- Product type
- Price
- Variant options
- Vendor
Filters use AND logic, and filter values use OR. For instance, you can return products that are a certain color and a certain size, or products that are one color or another.
When filters are applied, they appear in the collection or search URL through URL parameters.
Filter URL Parameters
Applied filters show up in the page URL as URL parameters according to the filter type. These URL parameters follow a specific structure.
Filters need to be created in the SHOPLINE admin before they can be applied.
URL Parameter Structure
Filter URL parameters include the following components:
| Parameter | Required | Description |
|---|---|---|
filter | Yes | The default namespace for filter URL parameters. |
filter_scope | Yes | The scope of the filter. Can be one of the following: - p - To note that the scope is on the product level.- v - To note that the scope is at the variant level. |
attribute | Yes | The attribute the filter is based on. For more information about available attributes, see Filter Types. |
attribute_scope | No | The attribute scope for options and price attributes. For more information, see Variant-specific Filters. |
value | Yes | The filter value. For more information about value formats, see 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 instance, if you were to use the following filters:
- A filter based on the skirt product type
- A filter based on the Color variant option, with a value of
blue
Then the URL parameters for each would be:
filter.p.product_type=skirt
filter.v.option.Color=blue
If these filters were applied to the all collection, then the URL for the collection would be:
/collections/all?filter.p.product_type=skirt&filter.v.option.Color=blue
Multiple Filters
You can have multiple filters, as shown below:
filter.v.price.gte=5&filter.v.price.lte=100
You can also filter by multiple values within the same filter. This can be achieved in two ways:
- Include several values in one parameter
- Include a parameter for each value
filter.v.option.Color=blue
filter.v.option.Color=blue&filter.v.option.Color=green
Filter Types
Filters can be applied at two levels:
Product-Specific Filters
The following outlines the product-specific filters and how they're shown as a URL parameter:
| Name | Description | Parameter Name | Accepted Parameter Values |
|---|---|---|---|
| Product tags | Filter based on specific product tags. | tag | A single product tag, or a comma-separated list of product tags. For instance new, or new,retro. |
| Vendor | Filter based on specific vendors. | vendor | A single vendor, or a comma-separated list of vendors. For instance first-vendor, or first-vendor,second-vendor. |
| Product type | Filter based on specific product types. | product_type | A single product type, or a comma-separated list of product types. For instance pants, or pants,skirt. |
Users can create up to 25 filters.
Here is an example of the complete URL parameter structure for product-specific filters:
// Product tag
filter.p.tag=new,retro
// Product type
filter.p.product_type=pants
// Product vendor
filter.p.vendor=shopline
Variant-Specific Filters
The following outlines the variant-specific filters and how they're shown as a URL parameter:
| Name | Description | Parameter Name | Accepted Parameter Values |
|---|---|---|---|
| Availability | Filter based on variant availability. | availability | One of the following: - 0 - Out-of-stock variants.- 1 - In-stock variants.- 0,1 - Variants with both stock statuses. |
| Variant option | Filter based on a variant choice, such as Material or Style.Variant choice filters also need to specify the choice name for the attribute_scope component of the URL parameter structure.For instance, option.Color. | option | A single variant option value, or a comma-separated list of variant option values. For instance yellow, or yellow,green. |
| Price | Filter based on variant price. Price filters also need a price condition specified for the attribute_scope part of the URL parameter structure. The following values are accepted: - lte - For prices less than or equal to the input value.- gte - For prices greater than or equal to the input value. | price | A single currency value in the store's default currency format. For instance, 10 or 9.90. |
Users can create up to 25 filters.
Here is an example of the complete URL parameter structure for variant-specific filters:
// Variant stock status
filter.v.availability=1
// Variant price
filter.v.price.lte=6
// Variant option
filter.v.option.Color=blue
When variant-specific filters are used, the url and featured_media attributes of the product object are updated to show the first variant that meets the current filter criteria.
The featured_media displays the main media of the first matching variant with media included, and the url attribute is updated to directly link the first matching variant.
