page-toc

Table of contents with scroll-spy highlighting. Auto-generates from headings or enhances existing manual markup.

Overview

The <page-toc> component creates a table of contents that highlights the current section as you scroll. It supports two modes:

  • Auto-generated: Scans the page for headings and builds the ToC automatically
  • Manual markup: Enhances existing navigation with scroll-spy (progressive enhancement)

Attributes

Attribute Type Default Description
levels string h2,h3 Comma-separated heading levels to include
scope string main CSS selector for content scope to scan
title string On this page Title shown above the ToC

Excluding Headings

Headings inside live examples or embedded content can pollute the table of contents. Add data-toc-ignore to exclude them.

On an ancestor container

All headings inside the marked container are skipped. This is the most common pattern for doc pages with inline examples:

On a single heading

Exclude an individual heading while keeping its siblings:

Auto-Generated Mode

When the component is empty, it automatically scans the page for headings (with IDs) and builds the table of contents.

Requirements

  • Headings must have id attributes (use heading-links to auto-generate)
  • Headings must be within the scope container (default: main)

Manual Markup Mode

For progressive enhancement, provide your own markup. The component will add scroll-spy behavior without modifying your structure.

CSS Classes

Class Purpose
.details Collapsible container
.summary ToC header/title
.nav Navigation wrapper
.list Links list
.item List item (use data-level for nesting)
.link Navigation link
.active Applied to current section link (auto-managed)

Scroll-Spy Behavior

The component uses IntersectionObserver to track which section is currently visible and highlights the corresponding link.

  • The first visible heading in the viewport is highlighted
  • Links receive the .active class and aria-current="true"
  • URL hash is updated when clicking links
  • Syncs with browser back/forward navigation

Responsive Behavior

The component adapts to different screen sizes:

Wide Screens (1024px+)

  • ToC is always visible
  • Position: sticky for sidebar placement
  • Full heading hierarchy shown

Narrow Screens

  • Collapsible disclosure pattern
  • Nested headings hidden (except active)
  • Click to expand/collapse

Sidebar Layout

Common pattern: ToC in a sidebar alongside main content.

Events

Event Detail Description
page-toc:navigate { id: string } Fired when a ToC link is clicked

JavaScript API

Method Description
refresh() Rebuild ToC after dynamic content changes

Accessibility

  • Uses semantic <nav> element with aria-label
  • Active link marked with aria-current="true"
  • Keyboard accessible - tab to navigate, enter to activate
  • Focus moves to heading after navigation
  • Respects prefers-reduced-motion for scroll behavior

Styling with CSS Custom Properties

The component uses scoped styles via @scope. Override these properties for customization:

  • --color-interactive - Active link color
  • --color-text-muted - Inactive link color
  • --color-surface-raised - Hover background
  • --border-width-medium - Active link border

Best Practices

  • Use with heading-links to ensure headings have IDs
  • Keep ToC visible on wide screens for easy navigation
  • Use levels="h2,h3" for most documentation pages
  • Add data-toc-ignore to example containers that include headings
  • Consider manual markup for static sites (better initial render)

Related

  • heading-links - Auto-generates heading IDs and anchor links
  • layout-sidebar - Sidebar layout for ToC placement
  • nav - Navigation landmark element
  • details - Collapsible disclosure (used internally)
↑