Skip to content

Latest commit

 

History

History
147 lines (104 loc) · 5.53 KB

README.md

File metadata and controls

147 lines (104 loc) · 5.53 KB
Raw

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.

Preview
(Live-demo and source)

Also check out a large demo and other examples.

Table of contents

Difference to other libraries?

  • ⚡ fast
  • 🐜 6.4kB (core) or 11.7kB (with UI helpers)
  • 🏆 Supported by modern browsers using ES6 features. 1,2,3,4
  • 🏋️‍♂️ Lifting complex logic from the developer.
  • 🔋 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'));
</script>

That's it!

Check out more examples.

Parser

The Schema can be directly parsed from HTML. For this, the structure has to be built according to following rules. All class names can be adapted to suite existing projects. See above example or other examples.

  • Group element
    • .filtering-group
    • data-group-name="color"
    • Filter element
      • .filtering-filter
      • data-filter-name="red"
  • Item element
    • .filtering-item
    • data-filter-color="red"
      (the attribute name ends with the group name and is assigned the filter name)

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