Table of Contents

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

import React from 'react';

import { Plate } from '@udecode/plate/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,
};

See also:

Scroll container

If your scrolling element is:

  1. EditorContainer - no additional setup needed
  2. Editor container - use useEditorContainerRef():
// Below <Plate> component
function EditorContainer({ children }: { children: React.ReactNode }) {
  const containerRef = useEditorContainerRef();
 
  return <div ref={containerRef}>{children}</div>;
}
  1. Ancestor of editor container - use useEditorScrollRef():
// 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

Plugin for generating table of contents.

Options

Collapse all

    Enable scrolling behavior.

    • Default: true

    Top offset when scrolling to heading.

    • Default: 80

    Custom function to query headings.

Transforms

insertToc

Insert table of contents element.

OptionsInsertNodesOptions<SlateEditor>

    Node insertion options.

Hooks

useTocElementState

Manage TOC element state.

Returns

Collapse all

    Document headings array.

    Heading scroll handler.

useTocElement

Handle TOC element interactions.

Parameters

Collapse all

    Scroll handler from useTocElementState.

Returns

Collapse all

    Props for TOC element.

useTocSideBarState

Manage TOC sidebar state.

Parameters

Collapse all

    Initial open state.

    • Default: true

    Intersection Observer root margin.

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

    Scroll top offset.

    • Default: 0

Returns

Collapse all

    Active section ID.

    Document headings.

    Mouse over TOC state.

    Sidebar open state.

    Set observation state.

    Set mouse over state.

    TOC element ref.

    Content scroll handler.

useTocSideBar

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

Parameters

Collapse all

    Mouse over TOC state.

    Sidebar open state.

    Set observation state.

    Set mouse over state.

    TOC element ref.

    Content scroll handler.

Returns

Collapse all

    Navigation element props.

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

    TOC item click handler.