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
itemsarray 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, anddata-toc-titleattributes.
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-labelor the<nav>wrapper
API
Props
| Prop | Type | Default | Description |
|---|---|---|---|
title | string | - | Optional heading text rendered above the link list. |
title_tag | Enum: strong, h2, h3, h4 | h3 | Tag used for the title element. |
items | array | - | Array of {url, text, children} link objects. children is an optional nested array of {url, text} objects. |
label | string | Table of contents | Accessible name for the navigation landmark. |
scope | string | - | CSS selector for the scrollspy target scope. |
offset | number | 0 | Scrollspy offset in pixels for sticky header clearance. |
classes | array | - | Additional CSS class words merged into the root element. |
attributes | object | - | Additional HTML attributes spread on the root element. |
Classes
| Class | Capability | Default | Description |
|---|---|---|---|
.sm | Size | - | Small. |
.md | Size | Yes | Medium. |
.lg | Size | - | Large. |
.sticky | Position | - | Pins the component to a viewport edge while scrolling. |
Attributes
| Attribute | Set by | Required | Description |
|---|---|---|---|
data-toc-scope | Consumer | - | CSS selector for the content scope the TOC indexes. Required for auto-generated mode. |
data-toc-selector | Consumer | - | CSS selector for the headings to index within the scope. |
data-toc-title | Consumer | - | Optional title text rendered above the auto-generated link list. |
data-toc-exclude | Consumer | - | When present on a heading inside the scope, that heading is skipped during auto-generation. |
data-scrollspy-target | Consumer | - | 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