Skip to main content

Toc

Table of contents generated from page headings. Scans a configurable content scope for a configurable heading selector, auto-assigns IDs to headings that need them, and builds a sticky-capable navigation list with active-item highlighting via scrollspy. Works without JS when server-side pre-built links are provided.

Supports two rendering modes:

  • Pre-built, links are rendered server-side via Twig and work without JavaScript. Pass an items array to the template.
  • Auto-generated, JavaScript scans a content scope for headings, assigns IDs where missing, and builds the link list dynamically. Configure via data-toc-scope, data-toc-selector, and data-toc-title attributes.

Both modes integrate with the scrollspy utility for active-item highlighting as the user scrolls. Supports sticky positioning, two-level nesting (e.g. h2 + h3), heading exclusion via data-toc-exclude, and scanning across multiple content containers.

Usage​

When to use

  • Long-form articles with multiple sections where readers need a roadmap
  • Reference documentation pages
  • Any page where jumping to a specific section saves scrolling

When not to use

  • Short pages where the TOC would be longer than the content
  • Pages with a single section
  • Primary site navigation - use navbar

Do

  • Give the TOC a <nav aria-label> so assistive tech can identify it
  • Keep the TOC scoped to a single content region (typically <main>)
  • Use sticky positioning so the TOC stays visible while scrolling
  • Exclude headings that aren't useful entry points with data-toc-exclude

Don't

  • Include every heading level - stick to one level (usually h2)
  • Let the TOC scroll independently of the page when it already fits
  • Omit the aria-label or the <nav> wrapper

API​

Props​

PropTypeDefaultDescription
titlestring-Optional heading text rendered above the link list.
title_tagEnum: strong, h2, h3, h4h3Tag used for the title element.
itemsarray-Array of {url, text, children} link objects. children is an optional nested array of {url, text} objects.
labelstringTable of contentsAccessible name for the navigation landmark.
scopestring-CSS selector for the scrollspy target scope.
offsetnumber0Scrollspy offset in pixels for sticky header clearance.
classesarray-Additional CSS class words merged into the root element.
attributesobject-Additional HTML attributes spread on the root element.

Classes​

ClassCapabilityDefaultDescription
.smSize-Small.
.mdSizeYesMedium.
.lgSize-Large.
.stickyPosition-Pins the component to a viewport edge while scrolling.

Attributes​

AttributeSet byRequiredDescription
data-toc-scopeConsumer-CSS selector for the content scope the TOC indexes. Required for auto-generated mode.
data-toc-selectorConsumer-CSS selector for the headings to index within the scope.
data-toc-titleConsumer-Optional title text rendered above the auto-generated link list.
data-toc-excludeConsumer-When present on a heading inside the scope, that heading is skipped during auto-generation.
data-scrollspy-targetConsumer-Set by the TOC on its root so the scrollspy utility highlights the active link as the user scrolls.

Examples​

Excluded headings​

Headings skipped via data-toc-exclude.

Pre-built nested​

Items authored in markup rather than scanned from the page, nested two levels deep.

Above content​

The navigation placed before the content it indexes, for a narrow page with no room for a side rail.

Auto-generated​

An empty <nav> that builds its own list from the headings inside data-toc-scope.

Auto-generated nested​

The same scan widened to h2, h3 through data-toc-selector, so the generated list carries the heading hierarchy.

Multiple scopes​

A scope selector matching several regions, whose headings are indexed into one list in document order.

Accessibility​

  • WCAG 2.2 AA
  • Wrapped in <nav aria-label="Table of contents"> so the landmark is distinct from other navigation on the page
  • Active link exposes current state to assistive technology via aria-current
  • Links use native anchor behavior (href="#section-id") so keyboard activation and focus movement are native
  • Heading targets are reachable by keyboard focus after the browser scrolls to them

Dependencies​

  • scrollspy - provides active-item highlighting as the user scrolls through the content scope

Progressive enhancement​

  • No JS: works when the TOC is pre-built server-side (via Twig) - plain anchor links navigate natively
  • With JS: scans the content scope, builds the link list dynamically, auto-assigns IDs to headings that need them, and drives active-item highlighting via scrollspy
  • How to enable: include the TOC helper script and optionally configure behavior via data-toc-* attributes
  • scrollspy - active highlighting dependency
  • navbar - different concept (site navigation)
  • content - typical content region the TOC targets