glossary-index

Interactive glossary wrapper with live search filtering and scroll-spy letter tracking.

Overview

The <glossary-index> component wraps a static <dl>-based glossary to add live search filtering, scroll-spy active letter tracking, and deep-link support. Without JavaScript, the glossary is fully readable with anchor link jump navigation.

<glossary-index> <nav class="glossary-jump" aria-label="Jump to letter"> <a href="#A">A</a> <a href="#B">B</a> <a href="#C">C</a> </nav> <section class="glossary-section" id="A"> <h2>A</h2> <dl> <dt><dfn>Accessibility</dfn></dt> <dd>The practice of making websites usable by everyone.</dd> <dt><dfn>ARIA</dfn></dt> <dd>Accessible Rich Internet Applications specification.</dd> </dl> </section> <section class="glossary-section" id="B"> <h2>B</h2> <dl> <dt><dfn>Breadcrumb</dfn></dt> <dd>A navigation pattern showing the user's location.</dd> </dl> </section> </glossary-index>

Attributes

AttributeTypeDefaultDescription
placeholder string "Filter terms..." Placeholder text for the search input
<glossary-index placeholder="Search glossary..."> <!-- glossary sections --> </glossary-index>

HTML Structure

The component expects a specific markup structure to enable progressive enhancement.

<!-- Each letter section follows this pattern --> <section class="glossary-section" id="P"> <h2>P</h2> <dl> <dt><dfn>Progressive Enhancement</dfn></dt> <dd>A strategy that starts with baseline content and layers on functionality.</dd> </dl> </section>

Required Classes

ClassElementPurpose
.glossary-jump nav Letter jump navigation bar
.glossary-section section Container for each letter group (must have an id matching the letter)

Content Elements

ElementPurpose
dl Definition list containing terms and descriptions
dt Term container
dfn The defined term (used as the search target)
dd Term definition

Behavior

  • Search filtering: A search input is injected above the glossary. Typing filters terms in real time, hiding non-matching sections.
  • Scroll-spy: As the user scrolls, the active letter in the jump navigation updates to reflect the currently visible section.
  • Deep links: URL hash is updated when clicking jump links, allowing direct links to specific letters.
  • Progressive enhancement: Without JavaScript, the static markup provides a fully functional glossary with working anchor links.

Accessibility

  • Jump navigation uses aria-label="Jump to letter" for screen reader context
  • Active letter in jump navigation is marked with aria-current="true"
  • Search input is labelled via the placeholder attribute
  • Filtered-out sections are hidden with display: none, removing them from the accessibility tree
  • Uses semantic <dl>, <dt>, <dd>, and <dfn> elements
  • Keyboard accessible — tab through jump links and search input

Related