Scans the headings on the page and builds a scroll-aware, clickable table of contents from them — ideal for long articles.
Add TableOfContents to long-form pages — documentation, in-depth articles, guides — so readers can jump straight to the section they need instead of scrolling through everything. Because it scans the page's actual headings at render time, the list of links always matches the content; there's no separate outline to keep in sync when sections are added or renamed.
The min prop hides the block on short pages where a table of contents would add noise rather than value. It pairs naturally with RichText, since that's usually where the headings it scans come from.
Typical use cases
A knowledge base or documentation article is the primary case — a guide with six or eight sections benefits immediately from a jump-to menu, since readers often already know which part they need. A long buying guide or size guide on a webshop is a less obvious but genuinely useful case, letting a shopper skip straight to 'How to measure' without scrolling past unrelated sections. A professional-services insights article — a legal or financial explainer, for example — often has the same shape: several distinct sub-topics under one long page, where a table of contents saves a reader from scanning the whole thing to find the one paragraph that answers their question.
Common mistakes
Setting levels too broad — including every heading level from top to bottom — turns the table of contents into a deep, cluttered outline instead of a quick overview; for most articles, top-level sections alone give a cleaner, more useful list. Forgetting the min threshold is the other common miss: without it, a short page with only two headings still shows a two-item table of contents, which looks like a mistake rather than a feature — set min to whatever heading count actually justifies the block appearing.
Because the block reuses each heading's own text verbatim as its link label, keep headings inside RichText reasonably short and scannable — a heading written as a full sentence looks fine in the body copy but crowds a compact sidebar list.
The links TableOfContents generates are real in-page anchors, so they work with keyboard navigation and browser back/forward, and let a screen-reader user jump straight to a section landmark instead of tabbing through the entire page from the top — a meaningful accessibility gain on long-form content, not just a navigation convenience. Place it near the top of the page, ideally alongside Breadcrumbs, so both orientation aids are visible before the reader starts scrolling. Clear heading structure also helps search engines understand a long page's layout — see SEO and structured data for how heading hierarchy factors into that.