Documentation - Design System

The Table of Contents component automatically generates navigation from document headings with scroll tracking and active section highlighting.

Overview

The Table of Contents (TOC) component enhances documentation navigation by automatically detecting headings within your content and creating an interactive outline. It tracks scroll position, highlights the active section, and provides smooth navigation between content sections.

Key Features

Automatic Heading Detection: Finds all h2, h3, and h4 elements in the main content area
Scroll Position Tracking: Updates active state based on viewport position
Responsive Design: Desktop sidebar and mobile drawer modes
Smooth Scrolling: Animated navigation between sections
Accessibility: Full keyboard navigation and screen reader support
Zero Configuration: Works out of the box with sensible defaults

Interactive Demo

Table of Contents Component

This component is currently active on this page!

Note: The TableOfContents component automatically scans the main page content for headings. Look to the right side of this page (or the mobile button on small screens) to see it in action!

It's detecting and organizing all the h2, h3, and h4 headings from this documentation page.

How It Works

Scans the <main> element for headings
Generates IDs for headings without them
Creates a nested navigation structure
Tracks scroll position with IntersectionObserver
Updates active state as you scroll

Usage

Basic Implementation

<script>
import TableOfContents from '$lib/shared/components/navigation/TableOfContents.svelte';
</script>

<!-- Add to your layout -->
<TableOfContents title="On this page" />

The component automatically:

Scans the main content area for headings
Generates IDs for headings without them
Creates the navigation structure
Tracks scroll position
Updates active states

With Custom Configuration

<TableOfContents 
	title="Contents"
	class="custom-toc"
/>

Behavior

Desktop Mode

On screens larger than 1280px, the TOC appears as a sticky sidebar:

Remains visible while scrolling
Highlights current section
Shows nested heading hierarchy
Smooth scroll on click

Mobile Mode

On smaller screens, the TOC transforms into:

Floating action button at bottom-left
Full-screen drawer when opened
Backdrop overlay
Touch-optimized interface
Auto-close on navigation

API Reference

Props

Prop	Type	Default	Description
`title`	`string`	`'Table of Contents'`	Title displayed in the TOC header
`class`	`string`	`''`	Additional CSS classes for custom styling

Events

The component handles all events internally:

Click: Navigate to section
Scroll: Update active state
Resize: Switch between desktop/mobile
Escape: Close mobile drawer

CSS Variables

Customize appearance with CSS variables:

.custom-toc {
	--toc-width: 250px;
	--toc-padding: var(--space-4);
	--toc-link-color: var(--typography-caption-color);
	--toc-active-color: var(--primary);
	--toc-background: var(--surface-secondary);
}

Heading Detection

Included Headings

The TOC includes headings from:

Main content area (<main> element)
Article sections
Documentation content

Excluded Areas

The TOC automatically excludes headings from:

Navigation elements (<nav>)
Dialog/modal content
Drawer components
Menu structures
Elements with data-exclude-from-toc attribute

Custom Exclusion

To exclude specific headings:

<!-- This heading won't appear in TOC -->
<h2 data-exclude-from-toc>Internal Note</h2>

Styling

Default Styles

The component comes with minimal, semantic styling:

Subtle borders and backgrounds
Clear visual hierarchy
Active state highlighting
Smooth transitions
Dark mode support

Custom Styling

Override styles with CSS classes:

/* Minimal style */
.toc-minimal {
	background: transparent;
	border: none;
}

/* Bordered style */
.toc-bordered {
	border: 1px solid var(--border);
	border-radius: var(--radius-lg);
}

Accessibility

Tab: Navigate through links
Enter/Space: Activate link
Escape: Close mobile drawer
Arrow keys: Navigate within TOC

Screen Readers

Semantic HTML structure
Proper ARIA labels
Role announcements
Focus management

Best Practices

Heading Structure: Use proper heading hierarchy (h2 → h3 → h4)
Descriptive Text: Write clear, descriptive heading text
Unique IDs: Ensure heading IDs are unique
Skip Links: Provide skip navigation options

Performance

Optimization Features

Intersection Observer: Efficient scroll tracking
Debounced Updates: Reduced rerender frequency
Lazy Initialization: Only creates TOC when needed
Minimal DOM Updates: Only updates changed elements

Large Documents

For documents with many headings:

<!-- Limit heading levels for performance -->
<style>
	:global(.toc-level-4) {
		display: none;
	}
</style>

Common Patterns

Documentation Sites

Perfect for technical documentation:

<div class="docs-layout">
	<aside class="sidebar">
		<TableOfContents />
	</aside>
	<main>
		<!-- Your content with headings -->
	</main>
</div>

Blog Posts

Enhance long-form content:

{#if showToc}
	<TableOfContents title="In this article" />
{/if}

Learning Resources

Guide users through tutorials:

<TableOfContents 
	title="Tutorial Steps"
	class="tutorial-toc"
/>

Troubleshooting

TOC Not Appearing

Check that headings exist in <main> element
Verify headings aren’t excluded
Ensure component is mounted
Check console for errors

Incorrect Active State

Verify heading IDs are unique
Check scroll container
Adjust intersection threshold
Review navbar height offset

Mobile Issues

Test drawer animation
Verify touch targets (44px minimum)
Check z-index conflicts
Test focus restoration

Navigation Tabs - Horizontal tab navigation
Toolbar - Action bars and toolbars
Pagination - Page navigation controls

Summary

The Table of Contents component provides essential navigation for documentation and long-form content. With automatic heading detection, responsive design, and comprehensive accessibility support, it enhances user experience without requiring configuration. The component adapts seamlessly between desktop and mobile interfaces while maintaining consistent behavior and visual design.