Table of Contents (TOC) optional

Hierarchical navigation component that auto-generates from page headings with scroll spy functionality for improved document navigation.

Overview

The TOC component provides sticky sidebar navigation that automatically generates from your page's heading structure. It includes scroll spy to highlight the current section and smooth scrolling to sections when clicked.

Key features:

• Auto-generation from H2 and H3 headings
• Scroll spy with active section tracking
• Smooth scroll to sections on click
• Sticky positioning for persistent visibility
• Nested structure for heading hierarchy
• Mobile responsive (hidden by default on small screens)
• Fully themeable with CSS design tokens

Basic Example

Create a TOC container and initialize it with JavaScript to auto-generate navigation from your content headings.

<aside class="focus-toc" id="myTOC"></aside>

<script>
  // Auto-generate TOC from page headings
  FocusUI.TOC.init('#myTOC', {
    contentSelector: '.content',
    headingSelector: 'h2, h3',
    title: 'On This Page'
  });
</script>

Variants

Size Variants

Adjust TOC size with .focus-toc-sm or .focus-toc-lg classes.

<!-- Small -->
<aside class="focus-toc focus-toc-sm" id="smallTOC"></aside>

<!-- Large -->
<aside class="focus-toc focus-toc-lg" id="largeTOC"></aside>

Borderless Variant

Remove border and shadow with .focus-toc-borderless for a minimal look.

<aside class="focus-toc focus-toc-borderless" id="myTOC"></aside>

Compact Variant

Reduce spacing between items with .focus-toc-compact.

<aside class="focus-toc focus-toc-compact" id="myTOC"></aside>

Style Variants

Choose from 5 different visual styles for active state indicators.

<!-- Left border indicator (default) -->
<aside class="focus-toc focus-toc-minimal" id="myTOC"></aside>

<!-- Background pill on active -->
<aside class="focus-toc focus-toc-pill" id="myTOC"></aside>

<!-- Dot indicators -->
<aside class="focus-toc focus-toc-dots" id="myTOC"></aside>

<!-- Vertical progress line -->
<aside class="focus-toc focus-toc-line" id="myTOC"></aside>

<!-- Auto-numbered entries -->
<aside class="focus-toc focus-toc-numbered" id="myTOC"></aside>

Common Patterns

Documentation Pages

Typical usage for documentation with sticky positioning and nested structure.

<div class="docs-layout">
  <aside class="sidebar">
    <!-- Main navigation -->
  </aside>

  <main class="content">
    <article>
      <h1>Page Title</h1>
      <h2>Section 1</h2>
      <p>Content...</p>
      <h3>Subsection 1.1</h3>
      <p>Content...</p>
      <h2>Section 2</h2>
      <p>Content...</p>
    </article>
  </main>

  <aside class="focus-toc" id="pageTOC"></aside>
</div>

<script>
  FocusUI.TOC.init('#pageTOC', {
    contentSelector: '.content article',
    headingSelector: 'h2, h3',
    title: 'On This Page',
    scrollOffset: 80
  });
</script>

Long Articles

For blog posts or articles with a simple TOC showing only top-level headings.

<div style="max-width: 800px; margin: 0 auto;">
  <aside class="focus-toc focus-toc-borderless" id="articleTOC"></aside>

  <article>
    <h1>Article Title</h1>
    <h2>Introduction</h2>
    <p>Content...</p>
    <h2>Main Topic</h2>
    <p>Content...</p>
    <h2>Conclusion</h2>
    <p>Content...</p>
  </article>
</div>

<script>
  FocusUI.TOC.init('#articleTOC', {
    contentSelector: 'article',
    headingSelector: 'h2', // Only H2, no nesting
    title: 'Table of Contents'
  });
</script>

Mobile Visibility

By default, TOC is hidden on mobile (<768px). Use .focus-toc-mobile to show it.

<!-- Hidden on mobile (default) -->
<aside class="focus-toc" id="desktopTOC"></aside>

<!-- Visible on mobile -->
<aside class="focus-toc focus-toc-mobile" id="mobileTOC"></aside>

Heading ID Generation

The TOC component automatically generates IDs for headings that don't have them, using a slug of the heading text.

// Heading without ID
<h2>Getting Started</h2>

// Automatically becomes
<h2 id="getting-started">Getting Started</h2>

// Special characters are removed
<h2>What's New in 2024?</h2>
// Becomes: id="whats-new-in-2024"

JavaScript API

The TOC component requires JavaScript for auto-generation and scroll spy functionality.

Initialize

FocusUI.TOC.init('#myTOC', {
  contentSelector: '.content',
  headingSelector: 'h2, h3',
  title: 'On This Page',
  scrollOffset: 100
})

Update

Regenerate TOC when headings change dynamically.

FocusUI.TOC.update('#myTOC')

Destroy

FocusUI.TOC.destroy('#myTOC')

Methods

Options

Accessibility

The TOC component follows accessibility best practices:

• Semantic HTML: Uses <nav> or <aside> with proper list structure
• Keyboard Navigation: All links are focusable and keyboard accessible
• Focus Visible: Clear focus indicators on links
• ARIA Labels: Consider adding aria-label="Table of Contents" to the container
• Color Contrast: Active links use primary color with sufficient contrast

<aside class="focus-toc" id="myTOC" aria-label="Table of Contents"></aside>

CSS Classes Reference

Complete list of CSS classes used by the TOC component:

Browser Support

The TOC component works in all modern browsers that support:

• CSS custom properties (variables)
• ES6 JavaScript (classes, arrow functions, spread operator)
• Smooth scrolling API (window.scrollTo({ behavior: 'smooth' }))
• Sticky positioning (position: sticky)

Tips and Best Practices