Table of Contents
The table of contents provides in-page navigation for long-form documents. It helps readers scan the structure of a page and jump directly to the section they need.
Use the TOC pattern inside Prose content on pages with three or more sections to help readers orient themselves and navigate directly to the content they need.
When to use
- The page has three or more distinct sections with headings — Fewer than three sections rarely justifies the added navigation overhead.
- Readers are likely looking for specific information rather than reading top-to-bottom — regulatory guidance, procedural manuals, reference documents, and policy summaries.
- The document is long enough that scrolling to find a section is inconvenient — If the full page fits comfortably on one or two screens, a TOC adds clutter without value.
Examples
Best practices
Place the TOC near the top
Position the TOC after any introductory content and before the first section. Readers need it before they start navigating.
Don't bury it mid-page
A TOC placed in the middle or at the bottom of a document is too late to help readers orient themselves.
Mirror the exact heading text
TOC links should use the same wording as the section headings they point to. Consistent labels help readers match what they see in the TOC with what they find on the page.
Don't paraphrase or abbreviate headings
Inconsistency between the TOC link text and the actual heading confuses readers looking for a match — especially screen reader users navigating by heading.
Limit to top-level sections
List only h2-level headings in the TOC to keep it scannable. A short, focused list lets readers find what they need at a glance.
Don't include every sub-heading
A deeply nested TOC that includes h3s and h4s defeats its purpose as a quick-scan navigation aid and becomes as overwhelming as the document itself.
Interaction behavior
- Smooth scroll — Clicking a TOC link smooth-scrolls to the target section. Users who prefer reduced motion see an instant jump instead.
- Active section highlight — As the reader scrolls, the active section highlights in the TOC, showing which section is currently in view. The active state updates automatically based on scroll position — no manual interaction needed.
- Keyboard navigation — TOC links are keyboard navigable — users can Tab through them and activate with Enter, following the standard link interaction model.
Returning to the top
Back-to-top links are the companion return path for the TOC. The TOC helps readers move down into a long document; a back-to-top link at the end of each h2 section lets them return to the TOC without manually scrolling back up.
Place one <p class="prose-back-to-top"> at the end of each h2 section's content. The link target should point back to the TOC container near the top of the page.
<article class="prose">
<nav class="prose-toc" id="article-toc" aria-label="Table of contents">
<p class="prose-toc-title">On this page</p>
<ul>
<li><a href="#overview">Overview</a></li>
<li><a href="#growth">Growth in NDFI Lending</a></li>
<li><a href="#call-report">Changes to the Call Report</a></li>
</ul>
</nav>
<h2 id="overview">Overview</h2>
<p>Section content...</p>
<p class="prose-back-to-top"><a href="#article-toc">Back to top</a></p>
</article>Place one after each h2 section
Treat back-to-top as the return half of the TOC pattern. Readers should be able to reorient after every major section, not just after finishing the entire page.
Don't add only one at the bottom
A single link at the very end breaks the navigation loop. It helps only readers who reached the bottom instead of supporting section-by-section movement.
See the Storybook FullPageNavigation story for the full working example of the paired TOC and back-to-top pattern.
Accessibility
- The TOC is wrapped in a
<nav>landmark witharia-label="Table of contents", so screen reader users can find it quickly from their landmarks list. - The title uses a
<p>element, not a heading. This avoids polluting the document outline with a "Table of contents" entry that would appear alongside the actual content headings. - TOC links use the same text as the target headings, so screen reader users hear consistent labels when navigating between the TOC and the document sections.