jQuery ListNav Plugin

This jQuery plugin supplies an easy way to unobtrusively add a letter-based navigation widget to any UL or OL list. An easily stylable (via CSS) nav bar appears above the list, showing the user the letters A-through-Z. Clicking one of the letters filters the list to show only the items in the list that start with that letter. Hovering over a letter (optionally) shows a count above the letter, indicating how many items will be displayed if that letter is clicked. Other options give you control over the basic functionality.

View the Demos

Features

  • Easy to unobtrusively add to existing lists
  • Works great on long lists: tuned for performance
  • Works on both UL and OL (numbered) lists: when using an OL the numbers start at 1 for each filtered letter
  • Can store the clicked letter in a cookie and reload the list using that letter (requires jquery.cookie plugin).
  • Can work on multiple lists on the same page (content reflows when list size shrinks and grows)
  • Designed with CSS styling in mind
  • Works when LI items are floated (which opens the door for some interesting use cases)
  • Works with any HTML inside LI’s: first letter of actual text is found and used for filtering
  • Demos are available to help you implement the plugin

Options

  • Optional hovering “record count” over each letter gives user a hint of how many items will appear
  • Optional “ALL” nav item lets your users see all the items in the list
  • Optionally loads up first letter that contains items (ie, if none start with A, but some start with B, B will preload)
  • Optionally force a specific letter to preload (ie, preload with C selected)
  • Optionally use a CSS class for making letters with no list items appear “disabled”
  • Optionally set the text that appears if a letter with no list items is clicked
  • Set the name of the cookie you’d like to store the last clicked letter in.
  • Optionally fire a custom javascript callback after a letter is clicked.
  • Optionally specify prefixes (like “The” or “A”) to ignore.
  • Optional ‘[…]’ menu item for access to list items that start with punctuation or chars like Ä and Ü.

Requirements

This plugin was developed and tested using jQuery 1.3.2 and tested using that and jQuery 1.2.6. We recommend using jQuery 1.3.2 or higher for the best performance.

Supported Browsers

We tested this plugin on Firefox 3.x (Windows/Mac), IE6, IE7, IE8/rc (Windows), Safari (Mac 3.2.1, Windows 4.0 beta), Google Chrome (Windows) and Opera 9.6.3 (Windows).

Usage

HTML convention for navbar placement

This plugin requires that you adhere to one convention so that you can control where each list’s navbar will appear on your page, and so that the plugin knows how to find the navbar div that corresponds to each list.

If the id of your list is “myList”, create a div like this, with the id “myList-nav”:

<div id="myList-nav"></div>
<ul id="myList">...

You can then bind listnav to myList and it will find the corresponding div to put the navigation bar in:

$('#myList').listnav();

CSS for your navbar

You can use any CSS you want to style your list navigation bar, but here’s a headstart, based on the jquery.listnav-2.1.css file used in the demos:

.listNav { margin:0 0 10px; }
.ln-letters { overflow:hidden; }
.ln-letters a { font-size:0.9em; display:block; float:left; padding:2px 6px; border:1px solid silver; border-right:none; text-decoration:none; }
.ln-letters a.ln-last { border-right:1px solid silver; }
.ln-letters a:hover,
.ln-letters a.ln-selected { background-color:#eaeaea; }
.ln-letters a.ln-disabled { color:#ccc; }
.ln-letter-count { text-align:center; font-size:0.8em; line-height:1; margin-bottom:3px; color:#336699; }

Options

The listnav plugin is designed to work for most cases without setting options, but offers these options if you want to override the defaults:

Option Default Description
initLetter Letter that you would like the list to initialize at. IE, set it to ‘C’ and when the list gets bound the items starting with ‘C’ will be displayed.
includeAll true true = include the ‘All’ item in the nav bar.false = do not to include it.
includeOther false true = show the […] navigation item in the menu bar.false = do not show the […] navigation item.

You may want to use this if your list contains items that start with punctuation or characters other than A-Z and 0-9 (like Ä and Ü).

flagDisabled true true = apply the ‘ln-disabled’ class (see the jquery.listnav-2.1.css file for examples) to letters in the navbar that have no entries in the list. IE: it can be used to make those letters look ‘disabled’ using CSS.false = do not to apply the style.
noMatchText ‘No matching entries’ This is the text that appears in place of the list if the user clicks a letter that has no mathing entries. Set it to your own text to override the default.
showCounts true true = show the numerical count above each letter when they are moused-over.false = do not show it.
cookieName null If you would like listnav to ‘remember’ the last letter a user clicks and load the list at that letter when your user returns to the page, include the jquery.cookie plugin in your page and give this option a value that will be unique for your list. For example: cookieName:’my-main-list’. The cookie persists for the user’s session (it is not permanent).
onClick null Use this to fire a javascript callback function after a letter is clicked. The letter that was clicked is available as a parameter for your callback function. For example:onClick:function(letter){ alert(‘You clicked ‘ + letter); }

See Demo 5 in the demos for an example.

prefixes [] If you’d like “The New York Times” to appear under letter T and N, supply an array of prefixes, one for each prefix word you’d like to ignore (case does not matter):prefixes:[‘the’,’a’]

Example using multiple options:

$('#categoryList').listnav({
    initLetter: 'c',
    includeAll: false,
    includeOther: true,
    flagDisabled: false,
    noMatchText: 'Nothing matched your filter, please click another letter.',
    showCounts: false,
    cookieName: 'my-main-list',
    onClick: function(letter){ alert('You clicked ' + letter); },
    prefixes: ['the','a']
});

Support

Please post questions and feedback to the jQuery Plugins Forum. We’re active participants in the group. Use the word “listnav” in the subject line to make it easy for us to notice.

License

Dual licensed under the MIT and GPL licenses:

http://www.opensource.org/licenses/mit-license.php
http://www.gnu.org/licenses/gpl.html

Download

GitHub Logo

In the wild

We created this control for the business directory section of a local community site we work on in our spare time: www.hwy9.com. If you use the listnav plugin in one of your sites and would like to have it listed here, please let us know.