site-index

Interactive site keyword index with A-Z jump nav, search filtering, entry counts, display limits, sort options, and optional JSON data loading.

Overview

The <site-index> component enhances a static keyword index with A-Z jump navigation, search filtering with scope control, entry counts, display limits with expand/collapse, and sort options.

Without JavaScript, the static markup is a fully functional keyword index with CSS multi-column layout at wider viewports.

<site-index letters="all" limit="5"> <nav aria-label="Site index"> <section id="index-a"> <h2>A</h2> <ul> <li> <span class="index-term">accessibility</span> <ul class="index-refs"> <li><a href="/docs/accessibility">Guide</a></li> <li><a href="/docs/elements/native/input#aria"> Input ARIA</a></li> </ul> </li> <li> <span class="index-term">attributes</span> <ul class="index-refs"> <li><a href="/docs/attributes/">Reference</a></li> <li><a href="/docs/attributes/data-trust/"> data-trust</a></li> </ul> </li> </ul> </section> </nav> </site-index>

Attributes

AttributeTypeDefaultDescription
placeholder string "Filter index…" Placeholder text for the search input
letters string "entries" Jump nav mode: "entries" (only letters with entries), "all" (full A-Z strip, empty letters disabled), or "none" (hidden).
filter string — Search scope filter mode
sort string — Sort order for letter sections
limit number — Max topics per letter section before a "Show N more" toggle appears.
src string — URL to load index data from as JSON

Features

A-Z Jump Navigation

By default, the jump nav shows only letters that have entries. Set letters="all" to show all 26 letters with disabled states for empty ones. Scroll-spy highlights the current letter as the user scrolls.

<site-index letters="all"> <!-- Full A-Z strip; letters without entries are disabled --> </site-index>

Search Scope

The controls bar includes a scope dropdown:

  • By Topic (default) — matches only the topic heading (.index-term)
  • All — matches both topic headings and sub-entry link text (.index-refs a)

For example, searching "button" in "All" mode will find topics that have a "Button element" sub-entry even if "button" isn't in the topic name.

Entry Counts

The component automatically appends reference counts: (N) after each topic term and in each letter heading. This helps users see at a glance which topics have the most content.

Display Limit

When limit is set, letter sections with more topics than the limit show a "Show N more" toggle button. Clicking expands to show all entries; clicking again collapses back.

<site-index limit="3"> <!-- Sections with more than 3 topics show a "Show N more" button --> </site-index>

Sort Options

The controls bar includes a sort dropdown:

  • Alphabetical (default) — standard A-Z order
  • Most entries — reorders letter sections by total reference count, highest first

HTML Structure

The static markup uses semantic HTML with specific classes that the component recognizes.

<nav aria-label="Site index"> <section id="index-a"> <h2>A</h2> <ul> <li> <span class="index-term">accessibility</span> <ul class="index-refs"> <li><a href="/docs/accessibility">Guide</a></li> <li> <a href="/blog/a11y">A11y tips</a> <small>blog</small> </li> </ul> </li> </ul> </section> </nav>
Class / ElementPurpose
.index-term Topic heading text within a <span>
.index-refs Nested <ul> of page reference links
<small> Optional content-type pill (e.g., "blog", "tutorial")
id="index-X" Section ID for jump nav anchors (lowercase letter)

JSON Data Loading

When src is set, the component fetches index data and renders dynamically. Static markup serves as fallback.

<site-index src="/api/site-index.json" placeholder="Search index..." letters="all"> </site-index> [ { "term": "accessibility", "refs": [ { "label": "Guide", "href": "/docs/accessibility/" }, { "label": "Input ARIA", "href": "/docs/elements/native/input/" } ] }, { "term": "attributes", "refs": [ { "label": "Reference", "href": "/docs/attributes/" }, { "label": "data-trust", "href": "/docs/attributes/data-trust/", "type": "attribute" } ] } ]

Accessibility

  • Jump nav uses aria-label="Jump to letter"; disabled letters have aria-disabled="true"
  • Scroll-spy sets aria-current="true" on the active letter link
  • Search input and dropdowns have aria-label attributes
  • Expand/collapse buttons use aria-expanded
  • Filtered items use hidden to remove from the accessibility tree
  • Without JavaScript, the full index is visible and navigable

Related