A fast, in-page text filter for a list of HTML elements.

View on GitHub

About listfilter.js

ListFilter creates a fast, case-insensitive text filter against a list of HTML elements on a page. Sometimes you just need a little thing to do a thing, you know?


  • jQuery


This simple implementation finds an unordered list of class my-list, and prepends it with a text input that filters the li elements in the list.

var filter = ListFilter({
    listContainer: '',
    filterItemClass: 'li'

Here’s a more likely use, which creates a text input inside an existing page element with ID filter-list-input-container. That text input filters children of class filter-item inside a parent of ID filterable-list. The child elements may be grouped inside blocks of class filter-block, and if no children inside a block match the text filter, the entire block is hidden as well. You can try it out below.

var filter = ListFilter({
    inputContainer: '#filter-list-input-container',
    listContainer: '#filterable-list',
    filterItemClass: '.filter-item',
    filterBlockClass: '.filter-block'

A.L. West

  • Anaheim Angels
  • Houston Astros
  • Oakland Athletics
  • Seattle Mariners
  • Texas Rangers

A.L. Central

  • Chicago White Sox
  • Cleveland Indians
  • Detroit Tigers
  • Kansas City Royals
  • Minnesota Twins

A.L. East

  • Baltimore Orioles
  • Boston Red Sox
  • New York Yankees
  • Tampa Bay Rays
  • Toronto Blue Jays

N.L. West

  • Arizona Diamondbacks
  • Colorado Rockies
  • Los Angeles Dodgers
  • San Diego Padres
  • San Francisco Giants

N.L. Central

  • Chicago Cubs
  • Cincinnati Reds
  • Milwaukee Brewers
  • Pittsburgh Pirates
  • St. Louis Cardinals

N.L. East

  • Atlanta Braves
  • Miami Marlins
  • New York Mets
  • Philadelphia Phillies
  • Washington Nationals

The ListFilter API

When you create a new filter, these arguments are required:

  • listContainer: The parent HTML element containing the items to be filtered. You can pass this a jQuery-style ID or class, or an HTML tag name.
  • filterItemClass: The elements to be matched by the filter. You can pass this a jQuery-style class or a tag name.

When you create a new filter, these arguments are optional:

  • inputContainer: The HTML element in which to place the text-filter input. You should pass this a jQuery-style ID. If you do not provide this argument, the input will be inserted immediately before the listContainer.
  • inputPrompt: A text string that appears immediately before the text-filter input. Defaults to ‘Search list.’
  • inputClass: A CSS class to apply to the text-filter input element.
  • filterBlockClass: An HTML wrapper class used to group members filterItemClass (so you can include headers or other markup along with groups). You should pass this a jQuery-style class. During filtering, any member of filterBlockClass with no visible filter items will also be hidden.
var filter = ListFilter({
    listContainer: '', //required jQuery-style ID or class, or an HTML tag name
    filterItemClass: '', //required jQuery-style class or HTML tag name
    inputContainer: '', //optional jQuery-style ID
    inputPrompt: '', //optional string
    inputClass: '', //optional string
    filterBlockClass: '' //optional jQuery-style class