Filter Long HTML Lists (Alphebetically) — alphaListNav.js 🔤

Hey friends!

I’ve been tinkering with another little JavaScript helper-plugin lately, and thought I’d share it here: alphaListNav.js. AlphaListNav is about making very long HTML lists easier to navigate and making them shorter so the user doesn’t need to scroll down a whole page (or two) just to begin reading the next bit of content!

What Is alphaListNav.js

In short: it takes an HTML list (like <ul> or <ol>), and automatically generates an alphabetical navigation bar above it. Click a letter, and the list filters (or jumps) to items that begin with that letter.

Lightweight, no dependencies, no jQuery, just vanilla JavaScript + a little CSS. Perfect for directories, names, glossaries, lists of U.S. states or cities– anything with long lists where users might want to jump to “M” or “S” instead of scrolling forever.

You can check out the demo + documentation here.

Screenshots

Screenshot - Desktop view, animated gif — Desktop view

Screenshot - Mobile view, animated gif — Mobile view

How to Use It

Here’s how you drop it into your project:

Download the JavaScript and CSS file from the dist/ folder of the GitHub repo (alphaListNav.min.js & alphaListNav.min.css).
In your HTML’s <head> section, include the CSS:

<link rel="stylesheet" href="alphaListNav.min.css">

Then just before the body tag (</body>), include the JS:

<script src="alphaListNav.min.js"></script>

Structure your list:

<ul id="myList">
  <li>Apples</li>
  <li>Blueberries</li>
  <li>Carrots</li>
  <li>Eggplant</li>
  …etc…
</ul>

Initialize the plugin by passing in the ID (or the DOM element) of your list:

<script>
    new AlphaListNav('myList');
</script>

Optionally, you can pass in an options object to tailor behavior.

Options & What You Can Tweak

Here’s a table of the options you can set, and what they do. These are defaults + tweakable things from the latest version.

Option	Type	Default	What It Does
initHidden	boolean	true	If true, initially hides the list until a filter/navigation letter is selected (or unless includeAll is used).
initHiddenText	string or boolean	“Tap a letter above to view matching items”	Text to show while the list is hidden (if initHidden is true).
initLetter	string	”	Which letter to pre-select/filter by on load (e.g. ‘A’, ‘*’ for “all”) if you want it to start filtered.
includeAll	boolean	true	Whether to include an “All” option in the navigation that shows every item.
allText	string	‘All’	How the “All” button is labeled.
noMatchText	string	‘No matching entries’	Message shown when no items match a filter.
includeNums	boolean	true	Whether to include numeric initial characters (0-9) in the nav.
concatenateNums	boolean	true	If true, groups all numeric-starting items under one “0-9” or similar label.
includeOther	boolean	false	Include a category for “other” characters (non-alphanumeric) if needed.
flagDisabled	boolean	true	If a letter in the nav has no matching list items, mark it disabled (grayed out or styled differently).
removeDisabled	boolean	false	If true, hidden letters with no items won’t even appear in the nav.
prefixes	array (strings or regex)	[]	If you want to ignore certain prefixes (like “The”, “A”, etc.) when deciding what letter an item should be grouped under.
filterSelector	string	”	If your list items contain nested elements, this lets you point to which nested part to use for filtering (rather than whole <li> text).
showCounts	boolean	true	Whether hovering (or interacting) over nav letters shows counts of matching items.
showLetterHeadings	boolean	true	Whether letter headings (like “A”, “B”, etc.) are shown above each group in the filtered list layout.
letterHeadingTag	string	‘h3’	What HTML tag to use for the group headings in the filtered list (e.g. <h2>, <span>, etc.).

Why I Made It / What’s Fun

It’s satisfying to build something super usable. I love making UI feel responsive and intuitive.
There’s something pleasing about alphabet navigation: it feels classic, like flipping through an index in a book.
Vanilla JS means fewer dependencies, lighter load, fewer surprises.
It’s useful in tons of projects: directories, tag lists, archive pages, even for simple dashboards.

Live Demo & Docs

You can try it out, see all options, and view how it behaves under different settings on the official documentation/demo page:

alphaListNav.js Docs & Demo

Wrapping Up

I hope this is helpful to anyone that needs needs to deal with long lists of items on their website.

It’s open source (MIT license), free to use, remix, break, re-build, whatever you want. Repo is live on GitHub: elliottprogrammer/alphaListNav.js.

Would love to see what weird or cool lists people build with this. If you make something awesome, shoot me a link and maybe I’ll feature it in a future post!