site-map

Interactive HTML sitemap with current-page highlighting, auto-expand, and expand/collapse all controls.

Overview

The <site-map> component enhances a static HTML sitemap with current-page highlighting, auto-expanding the section containing the current page, and expand/collapse all controls. Without JavaScript, the sitemap is a fully functional nested list of links.

<site-map> <nav aria-label="Full site map"> <ul> <li> <details> <summary><a href="/docs/">Documentation</a></summary> <ul> <li><a href="/docs/quick-start/">Quick Start</a></li> <li> <details> <summary><a href="/docs/elements/">Elements</a></summary> <ul> <li><a href="/docs/elements/native/">Native</a></li> <li><a href="/docs/elements/web-components/">Web Components</a></li> </ul> </details> </li> </ul> </details> </li> <li><a href="/about/">About</a></li> <li><a href="/blog/">Blog</a></li> </ul> </nav> </site-map>

Attributes

AttributeTypeDefaultDescription
current string window.location.pathname Pathname of the current page to highlight
src string — URL to load sitemap data from as JSON

Current Page Highlighting

By default, the component uses window.location.pathname to detect the current page and highlight its link. Use current to override this, for example in server-rendered or testing contexts.

<site-map current="/docs/elements/web-components/"> <!-- sitemap markup --> </site-map>

The matching link receives an aria-current="page" attribute and a visual highlight. All ancestor <details> elements are automatically expanded to reveal it.

HTML Structure

The sitemap uses nested <details> and <summary> elements for collapsible sections, wrapped in a <nav> landmark.

<!-- Nested details/summary for collapsible sections --> <nav aria-label="Full site map"> <ul> <li> <details> <summary><a href="/section/">Section Title</a></summary> <ul> <li><a href="/section/page/">Page</a></li> <!-- deeper nesting as needed --> </ul> </details> </li> <li><a href="/standalone/">Standalone Page</a></li> </ul> </nav>

Structure Rules

  • Wrap the entire sitemap in <nav aria-label="Full site map">
  • Use <details>/<summary> for sections with children
  • Place the section link inside <summary>
  • Child pages go in a nested <ul> inside the <details>
  • Leaf pages are simple <li><a> elements

JSON Data Loading

When src is set, the component fetches sitemap data from the specified URL and renders the tree dynamically. Static markup serves as a fallback.

<site-map src="/api/sitemap.json" current="/docs/quick-start/"> </site-map>

Behavior

  • Auto-expand: The section containing the current page is automatically expanded on load.
  • Expand/collapse all: Control buttons are injected to expand or collapse all <details> sections at once.
  • Current page marking: The link matching the current pathname receives aria-current="page" and visual styling.
  • Progressive enhancement: Without JavaScript, the sitemap renders as a navigable nested list. Sections default to collapsed via <details>.

Accessibility

  • Uses <nav aria-label="Full site map"> for landmark navigation
  • Current page link is marked with aria-current="page"
  • Expand/collapse controls have descriptive accessible labels
  • <details>/<summary> provides native disclosure semantics
  • Keyboard accessible — tab through links, enter/space to toggle sections
  • Without JavaScript, all content is accessible via native HTML disclosure widgets

Related