✨ Product Filter™

Fast and highly customizable storefront-based filter for product feeds adapted for DEUS projects. The filter is built for use on collection pages as well as on the search page, but in principle it can be used anywhere. All that is needed is a proper data endpoint or ready-to-use array of product data objects, allowing even for filtering of products fetched from third-party sources such as Clerk or Algolia.

Table of contents

1. Installation
2. Example files
3. Data template
4. Usage
5. Required config settings
6. Optional config settings
7. Filter objects
   7.1. Required settings for all filters
   7.2. Required settings for specific types of filters
   7.3. Optional settings
8. Event hooks

1. Installation

In your project directory run the following command:

$ yarn add shopify-product-filter

2. Example files

Once the package has been installed, the following example files will be available in the /node_modules/shopify-product-filter/example-files folder. These files can be pasted more or less directly into your project to get the filter running in no time. File | Description | Directory --- | --- | --- collection.data.liquid | Collection data endpoint template. This is where the filter fetches its data from. Refer to the data template section for more info. | src/templates template-collection.liquid | Barebone collection page markup. | src/sections main.ts | Example scripts for collection page | resources/js/pages/collection

3. Data template

Before using the filter, a data template must be created. This template serves as the data endpoint for fetching the product data. The template must use {% layout none %} and its output must be a valid JSON array. The products should be paginated by 1000, and the data structure for each product data object in the array must follow the same structure as the regular Shopify product object returned by the product.json endpoint. And finally, the template suffix must be data.

Besides what you might need for building your product items etc., there are certain data that must be included for the different types of filters to work. The included collection.data.liquid file provides the minimal data to allow for the use of all filter types.

:bulb: If the filter you are building will not need to include e.g. product type, the product_type entry may be omitted from your data endpoint and so on. Cutting down to only the strictly necessary data for your specific usecase may improve performance.

4. Usage

import ProductFilter from 'shopify-product-filter';

const productFilter = ProductFilter({
  endpoint: `/collections/${collectionHandle}`,
  filters: [
    {
      name: 'size',
      type: 'option',
      optionName: 'Size',
      renderFunctions: [renderFunc],
      removeFunctions: [removeFunc],
      groupElements: [sizeFilterEl],
    },
    // more filter objects ...
  ],
  paginationElement,
  productCount,
  productOutput,
  productRenderFunction,
  // products, // if providing a ready-to-use products array, endpoint and productCount may be omitted. See the section on optional config settings for more info
  storeUrl,
});

5. Required config settings

| Key | Value | Description
| --- | --- | --- | | endpoint * | string | The path for the data endpoint. On collection pages this will usually be /collections/${collectionHandle}, and on the search page it will usually be /search?q=${searchQuery}. In principle however it can be anything, as long as the path points to an endpoint providing JSON data. You don't need to add the ?view=data parameter, as it is added automatically. | | filters | Array | The array must be populated with objects providing settings for each filter to be created. Refer to the list of filter types for the required settings for each filter type. | | paginationElement | HTMLElement | The element used to trigger the rendering of the next page. If paginationType is set to 'scroll', the paginationElement should always be placed at the bottom of the product feed. | | productCount * | number | The total number of products in the collection or the total number of products returned by the search. | | productOutput | HTMLElement | The element to render the product items to. | | productRenderFunction | Function | The function to render the HTML output for each product item. When run by the filter, the function will be passed a product object argument containing the product data, and an optional productRenderArguments object containing key-value pairs for additional custom arguments. | | storeUrl * | string | The store root URL

* If providing the config with a products entry, endpoint, productCount, and storeUrl may be omitted. See the section on optional config settings for more info.

6. Optional config settings

| Key | Value | Description | Default value | | --- | --- | --- | --- | | classes.groupClass | string | The class of the HTML elements that the filter will render the individual filter items to | 'filter-group' | | classes.itemClass | string | The class of the individual filter items | 'filter-item' | | classes.itemActiveClass | string | The class given to the filter items when they are active | 'filter-item--active' | | defaultSort | string | A string of the type SortValue | 'featured' | | pageSize | number | The number of products to be rendered at a time | 16 | | paginationType | string | Defines whether to click an element or to scroll to the bottom to render the next page. The allowed values are: 'button', 'scroll' | 'button' | | productRenderArguments | Object | An object containing key-value pairs with additional arguments to be passed to the product render function. | undefined | | products | array | An array of ready-to-use product data objects. This can be useful for filtering products provided by a third party source such as Clerk or Algolia. Note that the product data must still follow the same structure. If products are included, endpoint, productCount, and storeUrl may be omitted. In this case the data endpoint template is not required either. | undefined | | renderOnLoad | boolean | Tells the filter whether to render its first page once loaded. If prerendering the first page of products with liquid, this may be set to false. | true | | resetElements | Array | An array of elements that will serve as reset triggers for the filter. | [] |

7. Filter objects

7.1. Required settings for all filters

| Key | Value | Description | | --- | --- | --- | | name | string | The unique name of the filter. This is used in the URL parameters generated by the filter as well as internally in the filter. | | type | string | The type of the filter. The allowed values are: 'option', 'price' 'sort', 'tag', 'tagPrefix', 'type', 'vendor'. | | groupElements | Array | An array of elements to render the filter items to. If the filter only has one group element, it must still be entered as a single-item array. | | removeFunctions | Array | An array of functions to remove the filter in case it has no values. The number of functions in the array must equal the number of group elements and should be entered in the same order. | | renderFunctions * | Array | An array of functions to render the filter items in the filter group(s). The number of functions in the array must equal the number of group elements and should be entered in the same order. The render function is given two arguments value and className. The className value must be given as a class to the filter item, and the value value must be inserted as a data-value attribute. See the main.ts example file for reference. |

* Specifically if a group element is a <select> tag, its render function should always return an <option> tag.

7.2. Required settings for specific types of filters

| Filter type | Key | Value | Description | | --- | --- | --- | --- | | option | optionName | string | The actual name of the option as entered on the products | | sort | sortValues | Array | An array populated with objects each of which containing a title and a value. The value of title can be any string (allowing for translations), but the value of value must be one of the following: 'featured', 'title-ascending', 'title-descending', 'price-ascending', 'price-descending', 'created-ascending', 'created-descending'. | | sort | renderFunction | Function | Sort filters require a slightly different render function, as the first argument given to the function is a data object containing title and value. See the main.ts example file for reference. | | tagPrefix | prefix | string | The prefix used, e.g. 'color_' or 'fabric_'. | | price | renderFunction | Function | Price filters require a slightly different render function, as the first argument given to the function is a data object containing a min and max value. The min value must be inserted as a data-min attribute on the filter item, and the max value must be inserted as a data-max attribute. |

7.3. Optional settings

| Filter type | Key | Value | Description | | --- | --- | --- | --- | | option, tag, tagPrefix, type, vendor | singular | boolean | Defines whether more values can be selected at a time. If set to true, the user will only be allowed to select one value at a time (like with <radio> elements). | | tag | includeOnly | Array | An array of strings defining the tags to be included. All tags not included in the array will be omitted from the filter. | | tag | omit | Array | An array of string defining tags to be omitted. All tags included in the array will be omitted from the filter. | | option, tag, tagPrefix, type, vendor | sortOrder | Array | An array of strings defining the desired sort order for the values of the filter. By default the values will be sorted alphabetically. If given a sortOrder, the filter will attempt to sort its values in the order of the array. |

8. Event hooks

The filter fires a number of events at certain points. You can add a listener by using the on() method. The on() method requires a first parameter consisting of a valid string of the type ProductFilterEvent and takes a second function argument. When run, the function will be given an argument consisting of the filter object in its current state, which can be used to access the desired data.

productFilter.on('renderedProducts', (filter) => {
  /...
});

You can hook into the following events: Event | Description --- | --- fetchedProducts | All products have been fetched from the data endpoint. If a products array was provided in the filter config, this event will fire right away. renderedFilters | All the filter items have been rendered to their filter groups. createdQueries | Queries have been created from the URL filter parameters (if any). setFromQueries | All filter items have been set from the queries generated in the previous step. filteredProducts | The products have been filtered according to the queries. initializedFilters | Event listeners have been added to all filter items. initializedPagination | Event listener was added to the pagination element. setPagination | The filtered products have been split into pagination chunks, and the current page has been reset. itemChanged | The user (or a script) has changed a filter item. updatedURL | The URL was updated (based on filter changes). renderedProducts | The filtered products have been rendered to the product output. pageChanged | The next page of products has been rendered. reset | The filter has been reset