morphing-toc

A React table of contents component that displays minimal vertical lines and morphs into a full navigation menu on hover.

npmmorphing-toc GitHub

Interactive Playground

Try the component on the left. Adjust settings to see changes in real-time.

Thickness

Length

1.0

Theme

Features

•Minimal visual footprint with vertical lines
•Smooth morph animation on hover
•Auto-extracts headings from DOM
•Generates unique IDs for headings
•Smooth scrolling with configurable offset
•Fully customizable colors and sizes
•TypeScript support

Installation

npm install morphing-toc

Peer dependencies: react >= 18, react-dom >= 18, motion >= 11

Basic Usage

import { MorphingToc } from 'morphing-toc';

function BlogPost() {
  return (
    <div>
      <MorphingToc />
      <article>
        <h1>My Blog Post</h1>
        <h2>Introduction</h2>
        <p>...</p>
        <h2>Main Content</h2>
        <h3>Subsection</h3>
        <p>...</p>
      </article>
    </div>
  );
}

Props

Prop	Type	Default	Description
className	string	""	Custom CSS class for the container
scrollOffset	number	80	Offset from top when scrolling (px)
headingLevels	number[]	[2, 3, 4]	Which heading levels to include
skipFirstH1	boolean	true	Skip the first h1 (page title)
containerSelector	string	undefined	CSS selector to scope heading search
colors	MorphingTocColors	slate palette	Custom color configuration
sizes	MorphingTocSizes	default sizes	Custom size configuration

Customization

Custom Colors

<MorphingToc
  colors={{
    line: {
      h1: '#1e40af',
      h2: '#3b82f6',
      h3: '#93c5fd',
    },
    menu: {
      background: 'rgba(30, 64, 175, 0.95)',
      text: '#ffffff',
      textHover: '#bfdbfe',
    },
  }}
/>

Custom Sizes

<MorphingToc
  sizes={{
    lineWidth: {
      h1: '2rem',
      h2: '1.5rem',
      h3: '1rem',
    },
    menuWidth: '20rem',
  }}
/>

Scoped to Container

<MorphingToc
  containerSelector="#article-content"
  headingLevels={[2, 3]}
/>

Exports

The package also exports utilities for custom implementations:

import {
  MorphingToc,      // Main component
  useTocItems,      // Hook for heading extraction
  scrollToSection,  // Scroll utility
} from 'morphing-toc';

// Type exports
import type {
  MorphingTocProps,
  MorphingTocColors,
  MorphingTocSizes,
  TocItem,
} from 'morphing-toc';