Docs
Table of Contents

Table of Contents

Renders a table of contents element with clickable links to headings in the document.

Toc ElementToc Sidebar

Table of Contents

The Table of Contents (TOC) feature allows you to create an automatically updated overview of your document's structure.
How to use the Table of Contents:
  • Type "/toc" and press Enter to create the TOC.
  • The TOC updates automatically when you modify headings in the document.


Example Content

This is an example of content that would be reflected in the Table of Contents.

Subsection

Adding or modifying headings in your document will automatically update the TOC.

Benefits of Using TOC

A Table of Contents improves document navigation and provides a quick overview of your content structure.

Features

  • Automatically generates a table of contents from document headings
  • Smooth scrolling to headings

Installation

npm install @udecode/plate-heading @udecode/plate-node-id

Usage

import { TocPlugin, HeadingPlugin } from '@udecode/plate-heading/react';
import { NodeIdPlugin } from '@udecode/plate-node-id';
const plugins = [
  // ...otherPlugins,
  HeadingPlugin,
  NodeIdPlugin,
  TocPlugin.configure({
    options: {
      scrollContainerSelector: `#your-scroll-container-id`,
      topOffset: 80,
    },
  }),
];
const components = {
  // ...otherComponents,
  [TocPlugin.key]: TocElement,
};

Set scroll container

The TocPlugin requires a scroll container selector to function properly. This selector is used to identify the scrollable area containing your content.

TocPlugin.configure({
  options: {
    scrollContainerSelector: '#your-scroll-container-id',
  },
})

You can use any valid CSS selector:

  • ID: #scrollable-container
  • Class: .content-wrapper
  • Nested selector: body #main-content

Apply this selector to your <Editor /> component or a wrapper <div> around it, depending on your layout.

For consistency, use the same container for both TocPlugin and BlockSelectionPlugin.

Components

Examples

Plate UI

Refer to the preview above.

Plate Plus

  • Sticky TOC sidebar
  • Hover-to-expand: Opens automatically when you move your mouse over it
  • Interactive navigation: Click on items to smoothly scroll to the corresponding heading
  • Visual feedback: Highlights the current section in the sidebar
  • Beautifully crafted UI

Plugins

TocPlugin

Options

Collapse all

    Whether to use scrolling behavior.

    • Default: true

    The top offset to apply when scrolling to a heading.

    • Default: 80

    A custom function to query headings from the editor.

    The CSS selector for the scrollable container. Required to use scrolling behavior.

    • Default: '#scroll_container'

Transforms

insertToc

Inserts a table of contents element into the editor.

Parameters

Collapse all

    The editor instance.

    Options for inserting the TOC node.

Hooks

useTocElementState

Returns

Collapse all

    The editor instance.

    An array of heading objects in the document.

    A function to handle scrolling to a specific heading.

useTocElement

Parameters

Collapse all

    The editor instance.

    The scroll handler function from useTocElementState.

Returns

Collapse all

useTocSideBarState

This hook manages the state for the TOC sidebar.

Parameters

Collapse all

    Whether the TOC sidebar is open.

    • Default: true

    Root margin for the Intersection Observer.

    • Default: '0px 0px 0px 0px'

    Top offset for scrolling.

    • Default: 0

Returns

Collapse all

    ID of the currently active content section.

    The editor instance.

    List of headings in the document.

    Whether the mouse is currently over the TOC.

    Whether the TOC sidebar is open.

    Function to set the observation state.

    Function to set whether the mouse is over the TOC.

    Ref for the TOC element.

    Function to handle content scrolling.

useTocSideBar

This hook provides props and handlers for the TOC sidebar component.

Parameters

Collapse all

    The editor instance.

    Whether the mouse is currently over the TOC.

    Whether the TOC sidebar is open.

    Function to set the observation state.

    Function to set whether the mouse is over the TOC.

    Ref for the TOC element.

    Function to handle content scrolling.

Returns

Collapse all

    Props for the TOC navigation element.

    Handler for clicking on a TOC item.

Slash CommandAlignment