filtering.js

What is filtering.js

With filtering.js you can easily add filtering functionality to your project. It is a small, fast, and modern library without dependencies that can be used in node and browser environments.

^{(Live-demo and source)}

Also check out a large demo and other examples.

Always check the GitHub Wiki for breaking changes if you upgrade to a new major version!

Table of contents

• Difference to other libraries?
• Performance
• How to use?
• Parser
• API

---

Difference to other libraries?

• ⚡ Lightning fast
• 🐜 7.3kB (core) or 12.9kB (with UI helpers)
• 🏆 Supported by modern browsers using ES6 features. ^1,2,3,4
• 🏋️‍♂️ Lifting complex logic from the developer.
• 🔋 Automatically parse filter structure and items directly from HTML.
• 🔮 Info about how many items would be filtered. No more 0 results.
• 👪 Works in Node and Browser environment.

---

How to use?

npm i @filtering.js/filtering.js

Depending on the environment, there are builds for CommonJS, ESM and UMD located in the dist folder.

• Browser

<script src="/dist/umd/index.ui.js"></script>
<script>
    const {Filtering} = filteringjs;
</script>

• Webpack

import {Filtering} from "@filtering.js/filtering.js/ui";

• Node (module)

import filteringjs from "@filtering.js/filtering.js/core";

const {Filtering} = filteringjs;

If you don't need UI helpers like Parser or FilteringFlow, you can use the smaller core builds located at "/dist/umd/index.core.js" or "@filtering.js/filtering.js/core".

The preferred way to add filtering functionality to your project is by using the FilteringFlow helper class. It handles adding and removing of checked/disabled classes for filters and filtered classes for items. All classes can be adapted to easily suite existing projects too.

A simple, out of the box example:

<div id="root">
    <div>
        <div class="filtering-group" data-group-name="color">
            <div class="filtering-filter" data-filter-name="red">Red</div>
            <div class="filtering-filter" data-filter-name="blue">Blue</div>
        </div>
        <div class="filtering-group" data-group-name="size">
            <div class="filtering-filter" data-filter-name="small">Small</div>
            <div class="filtering-filter" data-filter-name="large">Large</div>
        </div>
    </div>

    <div>
        <div id="item-1" class="filtering-item" data-filter-color="red" data-filter-size="small"></div>
        <div id="item-2" class="filtering-item" data-filter-color="blue" data-filter-size="large"></div>
    </div>
</div>

<script>
    const {FilteringFlow} = filteringjs;
    new FilteringFlow(document.querySelector('#root')).filter();
</script>

That's it!

Check out more examples.

---

Parser (HTML Schema)

The Schema can be directly parsed from HTML. For this, the structure has to be built according to specific but very simple rules. Simply check out the previous HTML example. All class names and attributes can be adapted to suite existing projects, but for now, we use the default class names and attribute schemas.

• Root element
  • Group element
    • class="filtering-group"
    • data-group-name="color" (replace color with any name you want)
    • Filter element (descendant of a group element)
      • class="filtering-filter"
      • data-filter-name="red" (replace red with any name you want)
  • Item element
    • class="filtering-item"
    • data-filter-color="red" (the attribute derives from the group name color and filter name red)

---

Performance

Following tables illustrate the performance of the library measured on Desktop. The runtime is calculated by averaging 1.000 scenarios with various number of items, groups, and filters and also various number of checked filters.

100 items

filters per group \ groups	2	4	8
8	<1 ms	<1 ms	<1 ms
24	<1 ms	<1 ms	<1 ms
64	<1 ms	<1 ms	<1 ms

1.000 items

filters per group \ groups	2	4	8
8	<1 ms	2 ms	5 ms
24	<1 ms	2 ms	3 ms
64	<1 ms	2 ms	3 ms

---

API, Documentation and Examples

https://robertpainsi.github.io/filtering.js

• API
• Documentation
• Examples