Shopify-product-filter NPM

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

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

@grafikr/shopify-typescript

@infinitebrahmanuniverse/nolb-shop @everything-registry/sub-chunk-2753

2 years ago

2 years ago

2 years ago

2 years ago