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.
TocElement
: Renders table of contents elements.
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
: AssignsTocElement
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 theref
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 theref
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.
Transforms
tf.insertToc
Insert table of contents element.
Hooks
useTocElementState
Manage TOC element state.
useTocElement
Handle TOC element interactions.
useTocSideBarState
Manage TOC sidebar state.
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.
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.