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 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
- Tested on IE6, IE7, Firefox 2 and 3 (Windows and Mac), Safari (Windows and Mac)
- 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
Requirements
Requires jQuery 1.2+ (the code uses .slice()) and jQuery dimensions plugin OR jquery 1.2.6 (which includes dimensions plugin).
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 CSS you can see in the demos:
.listNav { margin:0 0 10px;}
.listNav a { font-size:0.9em; display:block; float:left; padding:2px 6px;
border:1px solid silver; border-right:none; text-decoration:none }
.listNav a.ln-last { border-right:1px solid silver; }
.listNav a:hover,
.listNav a.ln-selected { background-color:#eaeaea }
.listNav a.ln-disabled { color:#ccc }
.listNav .ln-letterCount { text-align:center; font-size:0.8em; line-height:1;
margin-bottom:3px; color:#336699; } /* extra styling using jquery.listnav.js internally used class name */
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 means to include the 'All' item in the nav bar. False means not to show it. |
| flagDisabled | true | True means to apply the disabledClass (see below) 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 means 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. |
| lastClass | 'ln-last' | This is the CSS class name that is used to style the right-hand border of the navigation control. |
| selectedClass | 'ln-selected' | This is the CSS class name used to style the 'selected' navigation letter. IE: when the user clicks 'A', this style gets applied to 'A'. |
| disabledClass | 'ln-disabled' | This is the CSS class name used to style 'disabled' letters (see the flagDisabled option above). |
| showCounts | true | True means to show the numerical count above each letter when they are moused-over. False means not to. |
Example using multiple options:
var opts = {
initLetter: 'c',
includeAll: false,
flagDisabled: false,
noMatchText: 'Nothing matched your filter, please click another letter.',
lastClass: 'letters-last',
selectedClass: 'letters-selected',
disabledClass: 'letters-disabled'
};
$('#categoryList').listnav(opts);
Support
Please post questions and feedback to the jQuery general discussion group. 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
Version 1.0.1 > Source: jquery.listnav-1.0.1.js. Packed:jquery.listnav.pack-1.0.1.js
Version 1.0.0 > Source: jquery.listnav-1.0.js. Packed:jquery.listnav.pack-1.0.js
Revisions
2008-10-07 Version 1.0.1 - Bug fix for LI's with nested lists
2008-10-02 Version 1.0.0 - Initial Release
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.