instaFilta in-page filtering plugin

Introduction

Imagine that you are developing a page that has a huge list or table of data that is being generated by the server. Now imagine that you are an end-user that needs to scroll through all that data in order to find what is needed. This is where instaFilta can greatly improve that experience by filtering out unwanted items in real-time as the user types in a text field.
That's pretty much it.

Oh, and it has a whole bunch of options available for you to customize that experince to your liking.

This demo page is meant to give you a quick idea if instaFilta is the right plugin for your project. Have you already decided? Great! Then you might want to get into the nitty gritty details. You will find everything you need on the instaFilta GitHub page.

Technical documentation and download

A simple example

The following shows an example of using instaFilta's default options. You simply apply the instaFilta function on a text field.

Try it out by entering some text in the input field above the target list. The plugin will bind to any elements having the CSS class instafilta-target and it will ignore character casing. As we will see in other examples, all of this can be customized through the plugin's options.

Carbon
Cobalt
Copper
Gallium
Gold
Hafnium
Iridium
Xenon

$('#my-input-field').instaFilta();

Target ALL the things!

The plugin will look for any text inside an element having the instafilta-target class. In this example, not only can you filter on these important people's names, you can also filter on the year they were born.

Name	Born
Albert Einstein	1879
Marie Curie	1867
Isaac Newton	1643
Henry Cavendish	1731
Edwin Hubble	1889

<tr class="instafilta-target">
    <td>Albert Einstein</td>
    <td>1879</td>
</tr>

Character casing and custom target classes

In this example, the filtering term must match the character casing of the target elements. The plugin will not match "mars" but it will match "Mars".

Also note that we can use a custom CSS class for our targets, if you need to adhere to naming conventions.

Mercury
Venus
Tellus
Mars
Jupiter
Saturn
Uranus
Neptune

$('#my-input-field').instaFilta({
    targets: '.planet-name',
    caseSensitive: true
});

Highlighting matching characters

By setting the markMatches option to true, you can highlight the matching text within the matching items in the list. The matching characters will get wrapped in a span element that has the instafilta-match CSS class. You can change this class by setting the matchCssClass option.

Superman
Wonderwoman
Batman
Spiderman
The Hulk
The Green Lantern
Elektra
Ant Man

$('#my-input-field').instaFilta({
    markMatches: true
});

Only match the beginning of a word

Easy! Just set the beginsWith option to true.

Bald Bull
Soda Popinski
Don Flamenco
Mike

$('#my-input-field').instaFilta({
    beginsWith: true
});

Using sections of lists

Many times, a large list of data will be grouped in some way. A group will typically contain a heading and perhaps more stuff. This example of animals is grouped by class, which is the heading for each group.

When filtering such a list, you probably want to hide the entire section, including heading etc. Just set the instafilta-section CSS class on the containing section element. That's it! And, you can of course customize that class name using the sections option.

Mammals

Bear
Badger
Moose
Hedgehog
Tiger
Orangutan
Wombat
Blue Whale

Reptiles

Snapping Turtle
Nile Crocodile
Tiger Snake
Green Iguana
Alligator
Chameleon
Gekko
Black Mamba

Birds

Ostrich
Atlantic Puffin
Flamingo
Hummingbird
Penguin
Albatross
Toucan
Mandarin Duck

<div class="instafilta-section">
    <h2>Birds</h2>
    <ul class="example-list">
        <li><span class="instafilta-target">Ostrich</span></li>
        <li><span class="instafilta-target">Atlantic Puffin</span></li>
        <li><span class="instafilta-target">Flamingo</span></li>
        <li><span class="instafilta-target">Hummingbird</span></li>
        <li><span class="instafilta-target">Penguin</span></li>
        <li><span class="instafilta-target">Albatross</span></li>
        <li><span class="instafilta-target">Toucan</span></li>
        <li><span class="instafilta-target">Mandarin Duck</span></li>
    </ul>
</div>

onFilterComplete returns matched hits

After the filtering process is done, you might want to report just how many hits were found and perhaps show some message if no hits were found. This example shows you how.

Peter
Lois
Stewie
Chris

var $myMessage = $('#some-result-message');

$('#my-input-field').instaFilta({
    onFilterComplete: function(matchedItems) {

        var message = (matchedItems.length > 0)
            ? "I found " + matchedItems.length + " matches!"
            : "I couldn't find a thing..";

        $myMessage.text(message);
    }
});

Categorize/tag items

This is a bit similar to using sections, but it has some important differences. You can tag individual target items with several categories. Do this by defining one or more (comma separated string or array) categories in a data-attribute associated with the categoryDataAttr option. You can then use the filterCategory method to perform filtering based on those categories.

In this example, a select box is used to filter out humans and machines. Note that "RoboCop" exists in both the machine category and the human category.

R2-D2
Terminator
John Connor
Andreas Weber
Johnny 5
Gordon Freeman
Wall-E
RoboCop

If the HTML looks like this..

<span class="instafilta-target" data-instafilta-category="human">Gordon Freeman</span>
<span class="instafilta-target" data-instafilta-category="machine">Wall-E</span>
<span class="instafilta-target" data-instafilta-category="human,machine,both">RoboCop</span>

..then we can filter it by category like this

var insta = $('#filtering').instaFilta();

/* This will show "Gordon Freeman" and "RoboCop" */
insta.filterCategory('human');

/* This will show "Wall-E" and "RoboCop" */
insta.filterCategory('machine');

/* This will only show "RoboCop" */
insta.filterCategory('both');

Yes, checkboxes!!

Given that we can feed several categories to the filterCategories method, we can create an interface that scoops up the values of checked checkboxes and use them for this pupose. Have a go at this example!

Europe Asia Africa

Sweden
India
Angola
Germany
Japan
Chad
Belgium
China
Ghana
Finland
Thailand
Kenya
Croatia
Vietnam
Madagascar
Belarus

The checkboxes look like this..

<input type="checkbox" value="europe">

..and the JavaScript looks like this:

var instaFilta = $('.continents').instaFilta();

var $myCheckboxes = $('.continent-check');

$myCheckboxes.on('change', function() {

    var checkedCategories = [];

    $myCheckboxes.each(function() {
        if ($(this).prop('checked')) {
            checkedCategories.push($(this).val());
        }
    });

    instaFilta.filterCategory(checkedCategories);
});

All or nothing

When applying multiple categories at once, instaFilta will match any matching categories. In some cases however, like this following example, you want to make sure that items only match if they belong to all categories.

Swims Walks Flies Trots

Ladybug
Porcupine
Bullshark
Crocodile
Camel
Iguana
Unicorn
Flying Fish

Example markup

<input type="checkbox" value="walks">
<input type="checkbox" value="flies">

<span class="instafilta-target" data-instafilta-category="walks,flies">Ladybug</span>

Example JavaScript (notice the second parameter, which is set to true)

var instaFilta = $('.animals').instaFilta();

var $myCheckboxes = $('.ability-check');

$myCheckboxes.on('change', function() {

    var checkedCategories = [];

    $myCheckboxes.each(function() {
        if ($(this).prop('checked')) {
            checkedCategories.push($(this).val());
        }
    });

    instaFilta.filterCategory(checkedCategories, true);
});