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,
};

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:
// 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>
  );
}

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.