Table of Contents

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

Toc ElementToc Sidebar
Loading...
Files
components/demo.tsx
'use client';

import React from 'react';

import { Plate } from '@udecode/plate-common/react';

import { editorPlugins } from '@/components/editor/plugins/editor-plugins';
import { useCreateEditor } from '@/components/editor/use-create-editor';
import { Editor, EditorContainer } from '@/components/plate-ui/editor';

import { DEMO_VALUES } from './values/demo-values';

export default function Demo({ id }: { id: string }) {
  const editor = useCreateEditor({
    plugins: [...editorPlugins],
    value: DEMO_VALUES[id],
  });

  return (
    <Plate editor={editor}>
      <EditorContainer variant="demo">
        <Editor />
      </EditorContainer>
    </Plate>
  );
}

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: {
      topOffset: 80,
    },
  }),
];
const components = {
  // ...otherComponents,
  [TocPlugin.key]: TocElement,
};

Scroll container

  • If your scrolling element is EditorContainer, you can skip this step.
  • If your scrolling element is the editor container, pass useEditorContainerRef() as the ref prop. For example:
// Should be rendered below <Plate> component
function EditorContainer({ children }: { children: React.ReactNode }) {
  const containerRef = useEditorContainerRef();
 
  return <div ref={containerRef}>{children}</div>;
}
  • If your scrolling element is an ancestor of the editor container, pass useEditorScrollRef() as the ref prop. For example:
// Should be rendered below <Plate> component
function Layout() {
  const scrollRef = useEditorScrollRef();
 
  return (
    <main ref={scrollRef}>
      <EditorContainer>
        <PlateContent />
      </EditorContainer>
    </main>
  );
}

Components

Examples

Plate UI

Refer to the preview above.

Plate Plus

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.

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.

TableToggle