Guide

This guide helps you get used to the library, especially so the parser and filtering-flow logic can lift all the heavy thinking from you. It will show you how to structure your HTML and how to enable some of the awesome features it comes out of the box with. It aims for beginners and may be a little long for many developers out there. If you’re an experienced developer and just want to see examples you just can copy and paste, check out the examples.

First example

Let’s get started by structuring the HTML.

<div id="root">      <!-- query the element by id in JavaScript -->
  <div>                <!-- group container with all the filters -->
    <div>Red</div>       <!-- filter -->
    <div>Blue</div>      <!-- filter -->
  </div>
  <div>                <!-- container with all items -->
    <div>Red item</div>  <!-- item -->
    <div>Blue item</div> <!-- item -->
  </div>
</div>

Nothing fancy yet! Everything is wrapped into an element with an id so we can easily query the root element. Filters and items are also placed nicely into a container element. Filtering.js doesn’t force you to structure your HTML in that way though. More on this when we start to add the required classes.

<div id="root">
  <div class="filtering-group">
    <div class="filtering-filter">Red</div>
    <div class="filtering-filter">Blue</div>
  </div>
  <div>
    <div class="filtering-item">Red item</div>
    <div class="filtering-item">Blue item</div>
  </div>
</div>

By adding the classes filtering-group for a group of filter, filtering-filter for filters and filtering-item for items, we tell the parser which items to look for. These class names are the default ones and can be changed by adapting the parser options.

…
<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>
…

You can think of the attribute data-group-name value as the equivalent to HTML’s input attribute name and the attribute value data-filter-name value as the equivalent to HTML’s input attribute value. Or in short

HTML	filtering.js
`input[name]`	`[data-group-name]`
`input[value]`	`[data-filter-name]`

Try to limit the used characters for data-group-name and data-filter-name to A-Z a-z 0-9 - _ or you may get into problems when linking filtering-items to their corresponding groups and filters.

Now that we’ve set up a group with filters, we just need to link the items to their corresponding filters. Nothing easier than this!

…
<div class="filtering-item" data-filter-color="red">Red item</div>
<div class="filtering-item" data-filter-color="blue">Blue item</div>
…

Note how the data-group-name value is used in the attribute name data-filter-color and the data-filter-name value is used as data-filter-color value.

Just one line of JavaScript code and “It’s Alive!”. Here is the final code:

<div id="root">
  <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>
    <div class="filtering-item" data-filter-color="red">Red item</div>
    <div class="filtering-item" data-filter-color="blue">Blue item</div>
  </div>
</div>

new filteringjs.FilteringFlow(document.querySelector('#root'));

Done! Hop to the examples to check out what features the library supports out-of-the-box, like

Only a single filter should be selected per group.
Add a select all filters filter.
Add a search input to prefilter items.
Add items into multiple filters of the same group.
Show number of results for each filter if it would be selected in advance.