Loading...

Features

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

Kit Usage

Installation

The fastest way to add table of contents functionality is with the TocKit, which includes pre-configured TocPlugin with the Plate UI component.

Add Kit

Add the kit to your plugins:

import { createPlateEditor } from 'platejs/react';
import { TocKit } from '@/components/editor/plugins/toc-kit';
 
const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    ...TocKit,
  ],
});

Manual Usage

Installation

pnpm add @platejs/basic-nodes @platejs/toc

Add Plugins

Include TocPlugin and HnPlugin in your Plate plugins array when creating the editor.

import { TocPlugin } from '@platejs/toc/react';
import { H1Plugin, H2Plugin, H3Plugin } from '@platejs/basic-nodes/react';
import { createPlateEditor } from 'platejs/react';
 
const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    H1Plugin,
    H2Plugin,
    H3Plugin,
    TocPlugin,
  ],
});

Configure Plugin

Configure the TocPlugin with custom component and scroll options.

import { TocPlugin } from '@platejs/toc/react';
import { H1Plugin, H2Plugin, H3Plugin } from '@platejs/basic-nodes/react';
import { createPlateEditor } from 'platejs/react';
import { TocElement } from '@/components/ui/toc-node';
import { H1Element, H2Element, H3Element } from '@/components/ui/heading-node';
 
const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    H1Plugin.withComponent(H1Element),
    H2Plugin.withComponent(H2Element),
    H3Plugin.withComponent(H3Element),
    TocPlugin.configure({
      node: { component: TocElement },
      options: {
        topOffset: 80,
        isScroll: true,
      },
    }),
  ],
});
  • node.component: Assigns TocElement to render table of contents elements.
  • options.topOffset: Sets the top offset when scrolling to headings.
  • options.isScroll: Enables scrolling behavior to headings.

Insert Toolbar Button

You can add this item to the Insert Toolbar Button to insert table of contents elements:

{
  icon: <TableOfContentsIcon />,
  label: 'Table of contents',
  value: KEYS.toc,
}

Scroll Container Setup

  • 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:
// 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:
// Below <Plate> component
function Layout() {
  const scrollRef = useEditorScrollRef();
 
  return (
    <main ref={scrollRef}>
      <EditorContainer>
        <PlateContent />
      </EditorContainer>
    </main>
  );
}

Plate Plus

Plugins

TocPlugin

Plugin for generating table of contents.

Options

  • isScroll optional boolean

    Enable scrolling behavior.

    • Default: true
  • topOffset optional number

    Top offset when scrolling to heading.

    • Default: 80
  • queryHeading optional (editor: SlateEditor) => Heading[]

    Custom function to query headings.

Transforms

tf.insertToc

Insert table of contents element.

OptionsInsertNodesOptions<SlateEditor>

    Node insertion options.

Hooks

useTocElementState

Manage TOC element state.

Returns

Collapse all
  • headingList Heading[]

    Document headings array.

  • onContentScroll (el: HTMLElement, id: string, behavior: ScrollBehavior) => void

    Heading scroll handler.

useTocElement

Handle TOC element interactions.

Parameters

Collapse all
  • onContentScroll (el: HTMLElement, id: string, behavior: ScrollBehavior) => void

    Scroll handler from useTocElementState.

Returns

Collapse all
  • props object

    Props for TOC element.

useTocSideBarState

Manage TOC sidebar state.

Parameters

Collapse all
  • open optional boolean

    Initial open state.

    • Default: true
  • rootMargin optional string

    Intersection Observer root margin.

    • Default: '0px 0px 0px 0px'
  • topOffset optional number

    Scroll top offset.

    • Default: 0

Returns

Collapse all
  • activeContentId string

    Active section ID.

  • headingList Heading[]

    Document headings.

  • mouseInToc boolean

    Mouse over TOC state.

  • open boolean

    Sidebar open state.

  • setIsObserve React.Dispatch<React.SetStateAction<boolean>>

    Set observation state.

  • setMouseInToc React.Dispatch<React.SetStateAction<boolean>>

    Set mouse over state.

  • tocRef React.RefObject<HTMLElement>

    TOC element ref.

  • onContentScroll (options: { id: string; behavior?: ScrollBehavior; el: HTMLElement }) => void

    Content scroll handler.

useTocSideBar

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

Parameters

Collapse all
  • mouseInToc boolean

    Mouse over TOC state.

  • open boolean

    Sidebar open state.

  • setIsObserve React.Dispatch<React.SetStateAction<boolean>>

    Set observation state.

  • setMouseInToc React.Dispatch<React.SetStateAction<boolean>>

    Set mouse over state.

  • tocRef React.RefObject<HTMLElement>

    TOC element ref.

  • onContentScroll (options: { id: string; behavior?: ScrollBehavior; el: HTMLElement }) => void

    Content scroll handler.

Returns

Collapse all
  • navProps object

    Navigation element props.

  • navProps.onContentClick (e: React.MouseEvent<HTMLElement, MouseEvent>, item: Heading, behavior?: ScrollBehavior) => void

    TOC item click handler.