Components

Table of contents (TOC)

On long docs pages, an empty nav (or container) with id="toc" is filled at runtime with nested links to every h1–h6 inside main#main, excluding headings that sit under .toc-exclude. The script is wckdToc in wckd-ui.js (default bootstrap). List appearance is reset via #toc ol / #toc li in wckd-ui-components.css.

Jump to:

Download & setup

Download WCKD UI Style guide

Start with the package download and setup steps in Get Started, then use the style guide for utility and token references while implementing this component.

Default implementation

Layout contract

The page should expose one main with id="main" and one element with id="toc". The snippet is the minimum shape; the script overwrites the contents of #toc on load.

In your template

Place an empty nav (or div) with id="toc" in a column or rail. wckdToc appends a nested ol and wire scroll/intersection for .active on the matching link.

Illustrative output

Structure only, real pages get live links to heading ids.

Markup

<main id="main">
  <h2 id="intro">Introduction</h2>
  <p>...</p>
</main>
<nav id="toc" aria-label="On this page"></nav>

Configuration options

Start from the default implementation, then apply one of these intent-driven variations based on your content and interaction goals.

Excluding regions

Headings inside an element with class toc-exclude are not added to the TOC. Use for repeated headers in components, ad regions, or secondary “Example” labels.

Add class="toc-exclude" to a wrapper around content whose headings should not appear in the rail. The script still runs against the same #main tree; only matching headings are skipped.

<div class="toc-exclude">
  <h3>Demo only</h3>
</div>

Markup

<div class="toc-exclude">
  <h3>Not listed in TOC</h3>
</div>

When to use

  • Policy, API, and help-centre pages with long scroll and many subsections.
  • Side-by-side layout: article in main, TOC in a narrow column; match your grid with utilities from the style guide.

Implementation notes

  • Only one id="toc" is valid in HTML; duplicate IDs will break getElementById behaviour in the initialiser.
  • H2 links in the generated list receive text-l and text-bold for visual hierarchy; adjust in wckdToc if your design system needs different classes.
  • The script sets unique id attributes on headings that are missing them, derived from their text, ensure final heading text is stable before release.

Developer checklist

  • Keep wckdToc in the bootstrap for pages that include #toc; remove it for microsites that do not use the pattern to avoid a no-op query.
  • Test with real content: duplicate heading text can produce non-unique ids, assign explicit ids on important anchors when needed.

← All components