toc-hero
image
TOC Block

The shape of a long page, at a glance.

An on-this-page contents list built from the page's own headings, with the current section highlighted as the reader scrolls.
inline-text-overlay
16.0
10.0
9.0
16.0

When to use

  • Long reference pages — a reader arriving from search needs to see the shape of the page before committing to it.
  • Documentation layouts — in a narrow Column beside the content, where it stays in view while the reader scrolls. This page is one.
  • Single-column pages — at the top of the content, as a jump list.

Skip it on short pages. With fewer than two headings to list, the block renders nothing.

Key decisions

  • Depth: H2 and H3 suits most pages. Use H2 only on a page with many subsections, where the full list would be longer than the page it describes.
  • Highlight current section: leave it on unless the page is too short for the highlight to change.
  • Placement: a 25% Column beside a 75% content Column. The TOC is sticky on wide screens and renders inline above the content on phones.

How the list is built

The contents list beside this column is the block itself. Nothing is authored beyond its three settings, so there is nothing to maintain when a heading is added, removed or renamed.

Headings supply their own anchors

EDS gives every heading an id from its text, so the links work without any authoring. Do not set a block ID to a heading's slug: the heading already carries it, and a duplicate id breaks the link.

Hidden content is left out

Headings inside an accordion item, tab panel, carousel slide or modal are skipped, because a link that scrolls to something the reader cannot see is worse than no link. A TOC placed inside one of those containers lists only that container's headings.

The highlight follows reading order

The current entry is the earliest heading in the top 30% of the viewport, or else the last heading scrolled past. A clicked entry stays marked until its heading moves, so a short final section can still be selected.

If a heading you expect is missing from the list, it is almost certainly inside an accordion, tab or carousel.

All authoring options

General

title: heading above the list. Default "On this page"
depth: h2 (H2 only) | h3 (H2 and H3, default) | h4 (H2, H3 and H4)
scrollSpy: boolean — highlight the current section. Default on

Analytics

classes_track-inview: emit an event when the block scrolls into view
classes_track-link-click: emit an event, with the target heading id, when an entry is clicked
meta: block-level analytics meta, sent as a JSON string

Events emitted:

emu-toc:inview
emu-toc:link:click
On this page
h3
true