Back to demos

Table of Contents DemoLink to section

This page demonstrates the scroll-spy table of contents functionality with nested headings and automatic highlighting.

Getting StartedLink to section

The table of contents automatically tracks your scroll position and highlights the current section. It also expands and collapses nested sections as you navigate through the document.

InstallationLink to section

To use the table of contents in your project, you need to import the required components:

import TableOfContents from '@/components/TableOfContents/TableOfContents.astro'
import { generateToC } from '@/utils/generateToC'

ConfigurationLink to section

The table of contents accepts several configuration options:

  • minHeadingLevel: The minimum heading level to include (default: 2)
  • maxHeadingLevel: The maximum heading level to include (default: 3)
  • tableOfContents: Whether to show the ToC at all (default: true)

FeaturesLink to section

The table of contents implementation includes several key features that enhance the user experience.

Scroll SpyLink to section

The scroll spy functionality uses the Intersection Observer API to efficiently track which headings are currently visible in the viewport. As you scroll through the document, the corresponding table of contents item is automatically highlighted.

How It WorksLink to section

  1. The IntersectionObserver monitors all headings within the configured range
  2. When a heading enters or leaves the viewport, the observer updates the active state
  3. The ToC automatically highlights the most relevant heading based on scroll position

Performance OptimizationsLink to section

The implementation includes several performance optimizations:

  • Throttled scroll events to prevent excessive updates
  • Efficient DOM queries using cached element references
  • CSS transitions are disabled during initial load to prevent flicker

Auto Expand/CollapseLink to section

Nested sections automatically expand when their parent section becomes active, and collapse when navigating away.

Behavior DetailsLink to section

  • Parent sections expand when any child section is active
  • Unrelated sections collapse to keep the ToC focused
  • Smooth transitions provide visual feedback

Mobile SupportLink to section

On mobile devices, the table of contents is accessible via a floating action button.

Mobile FeaturesLink to section

  • Slide-out drawer from the right side
  • Backdrop overlay for easy dismissal
  • Touch-friendly tap targets
  • Automatic closure when selecting a section

Advanced UsageLink to section

For more complex scenarios, you can customize the table of contents behavior.

Custom Heading LevelsLink to section

You can configure which heading levels are included in the table of contents:

Configuration in FrontmatterLink to section

---
tableOfContents: true
tocMinLevel: 1
tocMaxLevel: 4
---
Minimum Level SettingsLink to section

The tocMinLevel controls the highest level headings included.

Maximum Level SettingsLink to section

The tocMaxLevel controls the deepest level headings included.

Disabling the ToCLink to section

For pages that don’t need a table of contents:

Page-specific DisableLink to section

---
tableOfContents: false
---

Global ConfigurationLink to section

You can also disable globally in your layout.

Styling CustomizationLink to section

The table of contents uses CSS custom properties for easy theming:

Color CustomizationLink to section

.toc-link {
  /* Customize colors */
  color: var(--color-text);
}
Active State ColorsLink to section

The active link color can be customized:

.toc-link[aria-current="true"] {
  color: rgb(37 99 235); /* blue-600 */
}
Hover EffectsLink to section

Add custom hover effects:

.toc-link:hover {
  background-color: rgb(243 244 246); /* gray-100 */
}

Spacing and LayoutLink to section

Adjust spacing between items:

.toc-list {
  gap: 0.5rem;
}

Implementation DetailsLink to section

The table of contents consists of several interconnected components.

Component ArchitectureLink to section

  1. TableOfContents.astro: Main wrapper component
  2. TableOfContentsList.astro: Recursive list renderer
  3. starlight-toc.ts: Custom element with scroll-spy logic
  4. MobileToC.astro: Mobile-specific UI
  5. generateToC.ts: Utility for building hierarchical structure

Technical ConsiderationsLink to section

Browser SupportLink to section

The implementation uses modern web APIs:

  • Intersection Observer API
  • Custom Elements
  • CSS Custom Properties
  • CSS Grid and Flexbox

AccessibilityLink to section

The table of contents includes proper ARIA attributes:

  • aria-label for navigation context
  • aria-current for active state
  • Keyboard navigation support

ConclusionLink to section

This table of contents implementation provides a robust, performant solution for navigation in long documents. The scroll-spy functionality, automatic expand/collapse behavior, and mobile support create an excellent user experience across all devices.

On This Page