Eli Van Zoeren

A project I am working on needed a way to filter a long list of staff members. We needed to be able to filter by several different criteria, and several different interfaces (text search, dropdown lists). And it needed to happen in-place—no page reloads. Thus my listFilter jQuery plugin was born.

listFilter allows you to automatically filter out items from a list on the fly, using any number of criteria and data items. You can look at the example to see how it works.

How to use

First you need to inlude jQuery and the plugin script:

<script src=”/scripts/jquery.min.js”></script>
<script src=”/scripts/jquery.listfilter.js”></script>

You will need to things in you page: a list to filter and a form containing the controls you will use to set the filter criteria. These controls can be text inputs, textboxes, or select boxes. The list can be an actual list—<ul> or <ol>—or it can be any other element containing a group of similar elements (for instance a <table>, which contains <tr> elements). The trick here is that each filter criteria needs to match up with a sub-element of the list items. So if your list item looks like this: <li><h3 class=“name”>Name</h3> <p>Plumber</p></li>, you could have a criteria form that looks like this:

<form id=“criteria”>
  <label>Name:> <input type=“text” id=“name_filter” />
  <label>Job:> <input type=“text” id=“job_filter” />
</form>

You will notice that the id of each filter matches the class of an item in the list, with “_filter” added to the end. That is how the script knows what to filter.

Finally, you need to initialize the filtering with this line of code (either in the head of you document, or in an external script):

$(document).ready(function() {
$('#listToFilter').listFilter('#criteria');
});

There are three optional settings that you can pass to the listFilter function as a second parameter. listElement lets you specify the child element of #listToFilter that represents an individual item (default is “li”). transition specifies the effect used to show and hide the list items—can be “toggle”, “slide”, or “fade” (default is “toggle”). Finally, speed specifies the speed at which the transition will take place (default is 500). So if you wanted to filter the rows of a table by sliding unneeded rows up slowly, you would use:

$(document).ready(function() {
$('#tableToFilter').listFilter('#criteria', {listElement: 'tr', transition: 'slide', speed: 2000});
});

Download the script

Leave a comment if you have any questions or improvements. This plugin is loosely based on liveSearch by John Nunemaker as revised by John Resig.