Navigation

TableOfContents

On-page heading outline that renders nested anchor links and highlights the active section while scrolling.

import { TableOfContents } from '@lostgradient/cinder/table-of-contents';
navigationdocstoc
01

Overview

On-page heading navigation for long-form content and docs layouts.

Usage

svelte 
<script lang="ts">
  import TableOfContents from '@lostgradient/cinder/table-of-contents';
</script>

<TableOfContents target="#article-content" />

target also accepts a live HTMLElement reference in addition to the CSS-selector string shown above; the generated schema below documents the selector-only form since a live element reference isn't JSON-Schema-expressible.

Live preview

Overview

A quick summary of what this page covers.

Setup

Install dependencies and configure your environment.

Install packages

Install the dependencies needed for your project.

Configure project

Add and tune configuration values.

Deployment

Push your build to production.

02

When to use

Use when
  • Adding an "On this page" rail for long-form docs or settings screens.
  • Letting users jump between headings while keeping context via active-section highlighting.
Avoid when
  • Navigating between routes or top-level app areas — use navigation-bar or side-navigation.
  • The page has too few headings to justify a secondary navigation rail.
  • Rendering expandable hierarchical data with selection state. Use Tree instead
03

Examples

Derived from heading region

Automatically derives nested entries from headings in a target content region.

Explicit items

Uses a controlled nested items array for custom table-of-contents ordering.

04

Props

Props for table-of-contents
Name
Type
Default
Description
ariaLabel text 'On this page' Accessible name for the nav landmark.
items TableOfContentsItem[] Explicit TOC items. When provided, this source wins. If omitted, headings are derived from target + headingSelector.
target text Target heading container for derived mode. Accepts a CSS selector string or an HTMLElement.
headingSelector text 'h2, h3, h4' CSS selector for headings queried inside the target in derived mode.
observeRootMargin text '0% 0% -70% 0%' Root margin forwarded to IntersectionObserver when computing the active heading.
05

Accessibility