react-toc-builder

A lightweight and customizable React Table of Contents component for React and Next.js.

Automatically generate a responsive, nested Table of Contents from HTML headings (h2–h6) with SSR support, custom icons, DOMPurify sanitization, and full React 17–19 compatibility.

✨ Why react-toc-builder?

Most TOC libraries either:

• Only support Markdown
• Don't support SSR
• Require additional parsing libraries
• Have limited customization
• Don't work well with HTML generated by CMSs

react-toc-builder is designed to work directly with HTML content and integrates easily into React and Next.js projects.

Perfect For

• 📝 Blogs
• 📚 Documentation
• 📖 Knowledge Bases
• 🌐 Headless WordPress
• 📄 CMS Websites
• ⚛️ React Applications
• ▲ Next.js Applications
• 🧩 MDX Websites

🎬 Demo

🚀 Why Choose react-toc-builder?

| Feature | react-toc-builder | Typical TOC Libraries | |----------|-------------------|-----------------------| | HTML Input | ✅ | ⚠️ Usually Markdown only | | Nested Headings | ✅ | ✅ | | React 19 | ✅ | Varies | | Next.js App Router | ✅ | ⚠️ | | SSR | ✅ | ⚠️ | | Custom Icons | ✅ | ❌ | | SVG Icons | ✅ | ❌ | | DOMPurify | ✅ | ❌ | | Responsive | ✅ | ⚠️ | | SEO Friendly IDs | ✅ | ⚠️ |

🚀 Features

• ✅ Automatically generates a nested Table of Contents
• ✅ Supports HTML headings (h2–h6)
• ✅ Works with React 17, 18 & 19
• ✅ Fully compatible with Next.js App Router
• ✅ Server Side Rendering (SSR) support
• ✅ Responsive layout
• ✅ Custom icons
• ✅ SVG support
• ✅ SEO-friendly heading IDs
• ✅ DOMPurify sanitization
• ✅ Accessible navigation
• ✅ Lightweight bundle
• ✅ Easy CSS customization
• ✅ Zero configuration
• ✅ Smooth developer experience

🖼️ Output

Given HTML content with headings, react-toc-builder generates a nested, clickable Table of Contents like:

Contents
├─ Introduction
│   └─ Overview
└─ Getting Started

📦 Installation

npm install react-toc-builder

or

yarn add react-toc-builder

or

pnpm add react-toc-builder

or

bun add react-toc-builder

🚀 Quick Start

"use client";

import React from "react";
import {
  generateToc,
  TocWrapper,
} from "react-toc-builder";

const BlogContent = () => {
  const content = `
    <p>Welcome to my blog!</p>

    <h2>Introduction</h2>
    <p>This is the intro.</p>

    <h3>Overview</h3>
    <p>Some overview text.</p>

    <h2>Getting Started</h2>
    <p>Let's dive in!</p>
  `;

  const htmlWithToc = generateToc(
    content,
    1,
    "/toc-icon.png"
  );

  return (
    <TocWrapper html={htmlWithToc} />
  );
};

export default BlogContent;

📘 Next.js & TypeScript Support

Next.js App Router

TocWrapper uses React hooks internally.

If you are using Next.js App Router, add:

"use client";

at the top of the component file where you use TocWrapper.

TypeScript Support

react-toc-builder ships with its own type definitions, so it works out of the box with TypeScript — no manual declaration file needed.

If you ever hit a module resolution issue, you can fall back to creating react-toc-builder.d.ts with:

declare module "react-toc-builder";

📖 API Reference

generateToc(htmlContent, positionAfter, icon)

Generates a Table of Contents from HTML content.

Parameters

| Parameter | Type | Required | Default | Description | |---|---|---|---|---| | htmlContent | string | Yes | — | HTML string containing headings | | positionAfter | number | Yes | — | Insert TOC after this paragraph index (-1 inserts at the top) | | icon | string | No | undefined | Custom image URL or SVG string for the toggle icon |

Example

const htmlWithToc = generateToc(
  content,
  1,
  "/toc-icon.png"
);

TocWrapper

React component that safely renders generated TOC HTML.

Props

| Prop | Type | Required | Default | Description | |---|---|---|---|---| | html | string | Yes | — | Generated HTML from generateToc() |

Example

<TocWrapper html={htmlWithToc} />

🎨 Custom Icons

Image Icon

const htmlWithToc = generateToc(
  content,
  1,
  "/assets/toc-icon.png"
);

Custom SVG Icon

const customIcon = `
<svg
  width="18"
  height="18"
  viewBox="0 0 24 24"
  fill="none"
  stroke="currentColor"
  stroke-width="2"
>
  <polyline points="6 9 12 15 18 9"></polyline>
</svg>
`;

const htmlWithToc = generateToc(
  content,
  1,
  customIcon
);

🎨 Styling

The component uses simple CSS classes for customization.

.rtb-toc {
  border: 1px solid #e1e5e9;
  border-radius: 8px;
  margin: 20px 0;
  padding: 16px;
}

.rtb-toc-header {
  display: flex;
  align-items: center;
  justify-content: space-between;
}

.rtb-toggle-btn {
  cursor: pointer;
}

.rtb-toc-list {
  margin-top: 12px;
  padding-left: 0;
}

.rtb-toc-item {
  list-style: none;
  margin: 4px 0;
}

.rtb-toc-item a {
  text-decoration: none;
  color: #0366d6;
}

.rtb-toc-item a:hover {
  text-decoration: underline;
}

✅ Compatibility

| Framework | Supported | |---|---| | React 17 | ✅ | | React 18 | ✅ | | React 19 | ✅ | | Next.js App Router | ✅ | | Next.js Pages Router | ✅ | | Vite | ✅ | | Create React App | ✅ |

🎯 Use Cases

react-toc-builder is ideal for:

• Developer documentation
• Blogs
• Knowledge bases
• MDX websites
• Markdown rendering (after HTML conversion)
• CMS content
• Headless WordPress
• API documentation
• Technical articles

📁 Example Project Structure

my-app/
├── public/
│   ├── toc-icon.png
│   └── custom-icon.svg
├── src/
│   ├── components/
│   │   └── BlogContent.jsx
│   └── App.jsx
└── package.json

🔧 Advanced Usage

Multiple TOC Instances

const addTocToContent = (htmlContent) => {
  return generateToc(
    htmlContent,
    1,
    "/toc-icon.png"
  );
};

<TocWrapper html={addTocToContent(content)} />;

Insert TOC at Top

generateToc(content, -1);

Insert TOC After Second Paragraph

generateToc(content, 1);

🔒 Security

react-toc-builder sanitizes generated HTML using DOMPurify for safer rendering.

However, for maximum security, it is strongly recommended to sanitize untrusted CMS or user-generated HTML on your backend/server before passing it into generateToc().

📋 Requirements

• React 17+
• React DOM 17+
• Supports React 19
• Supports Next.js App Router

❓ FAQ

Does it work with React 19? Yes.

Does it support Next.js? Yes, both App Router and Pages Router.

Does it support SSR? Yes.

Can I use Markdown? Yes, after converting Markdown to HTML.

Can I customize the CSS? Yes, via the .rtb-* class names.

Can I use my own icons? Yes, either an image URL or an inline SVG string.

🗺️ Roadmap

• Active heading highlighting on scroll
• Smooth scrolling to sections
• Built-in theme support (light/dark)
• Additional TOC position options
• Custom animation options

🤝 Contributing

Contributions are welcome.

Development Setup

git clone https://github.com/rakeshdhiman644/react-toc-builder.git

cd react-toc-builder

npm install

npm run build

Local Testing

Inside package folder:

npm link

Inside React app:

npm link react-toc-builder

🐛 Bug Reports

Found a bug?

If you find a bug or have a feature request, please open an issue:

https://github.com/rakeshdhiman644/react-toc-builder/issues

📝 Changelog

See CHANGELOG.md

📄 License

MIT License © Rakesh Dhiman

🔗 Links

• NPM: https://www.npmjs.com/package/react-toc-builder
• GitHub: https://github.com/rakeshdhiman644/react-toc-builder

👨‍💻 Author

Rakesh Dhiman

• GitHub: https://github.com/rakeshdhiman644
• LinkedIn: https://www.linkedin.com/in/rakesh-kumar-881176177

⭐ If you found this package useful, please consider starring the repository.