Heading

Heading adds six block element types, h1 through h6, for document structure. Each level is its own plugin with the same block behavior, HTML parser, toggle transform, and optional Markdown shorthand rule. This page covers registry setup, manual setup, value shape, shortcuts, input rules, and Markdown serialization.

Features

• Block h1 through h6 elements.
• Individual H1Plugin through H6Plugin exports.
• Grouping HeadingPlugin and BaseHeadingPlugin with configurable levels.
• Bound editor.tf.h1.toggle() through editor.tf.h6.toggle() transforms.
• # through ###### input rules with HeadingRules.markdown().
• mod+alt+1 through mod+alt+6 shortcuts in the registry kit.
• Editable and static registry heading components.

Fast Path

Add Basic Blocks

BasicBlocksKit installs paragraph, H1-H6, blockquote, and horizontal rule plugins with Plate UI components. For headings, it configures every level with HeadingRules.markdown(), H*Element, a reset-on-empty break rule, and mod+alt+<level> shortcuts.

import { createPlateEditor } from 'platejs/react';

import { BasicBlocksKit } from '@/components/editor/plugins/basic-blocks-kit';

export const editor = createPlateEditor({
  plugins: BasicBlocksKit,
});

Render Headings

heading-node exports H1Element through H6Element. Each component renders a PlateElement with the matching heading tag and navigation-highlight styles.

Add Static Rendering

Use BaseBasicBlocksKit when rendering read-only content with platejs/static.

Ownership

BasicBlocksPlugin and BaseBasicBlocksPlugin are package grouping plugins. They do not install registry UI components; use the registry kits when you want the Plate UI heading styles.

Manual Setup

Install Package

npm install @platejs/basic-nodes

Add Individual Levels

Use individual level plugins when you want registry components, shortcuts, or per-level configuration.

import { HeadingRules } from '@platejs/basic-nodes';
import {
  H1Plugin,
  H2Plugin,
  H3Plugin,
  H4Plugin,
  H5Plugin,
  H6Plugin,
} from '@platejs/basic-nodes/react';
import { createPlateEditor } from 'platejs/react';

import {
  H1Element,
  H2Element,
  H3Element,
  H4Element,
  H5Element,
  H6Element,
} from '@/components/ui/heading-node';

export const editor = createPlateEditor({
  plugins: [
    H1Plugin.configure({
      inputRules: [HeadingRules.markdown()],
      node: { component: H1Element },
      rules: { break: { empty: 'reset' } },
      shortcuts: { toggle: { keys: 'mod+alt+1' } },
    }),
    H2Plugin.configure({
      inputRules: [HeadingRules.markdown()],
      node: { component: H2Element },
      rules: { break: { empty: 'reset' } },
      shortcuts: { toggle: { keys: 'mod+alt+2' } },
    }),
    H3Plugin.configure({
      inputRules: [HeadingRules.markdown()],
      node: { component: H3Element },
      rules: { break: { empty: 'reset' } },
      shortcuts: { toggle: { keys: 'mod+alt+3' } },
    }),
    H4Plugin.configure({
      inputRules: [HeadingRules.markdown()],
      node: { component: H4Element },
      rules: { break: { empty: 'reset' } },
      shortcuts: { toggle: { keys: 'mod+alt+4' } },
    }),
    H5Plugin.configure({
      inputRules: [HeadingRules.markdown()],
      node: { component: H5Element },
      rules: { break: { empty: 'reset' } },
      shortcuts: { toggle: { keys: 'mod+alt+5' } },
    }),
    H6Plugin.configure({
      inputRules: [HeadingRules.markdown()],
      node: { component: H6Element },
      rules: { break: { empty: 'reset' } },
      shortcuts: { toggle: { keys: 'mod+alt+6' } },
    }),
  ],
});

Use A Headless Group

Use BaseHeadingPlugin when you want to install several heading levels without configuring each level by hand.

import { BaseHeadingPlugin } from '@platejs/basic-nodes';
import { createSlateEditor } from 'platejs';

export const editor = createSlateEditor({
  plugins: [
    BaseHeadingPlugin.configure({
      options: {
        levels: [1, 2, 3],
      },
    }),
  ],
});

Value Shape

Headings are normal block elements. The heading level is the node type.

const value = [
  {
    children: [{ text: 'Installation' }],
    type: 'h1',
  },
  {
    children: [{ text: 'Install packages' }],
    type: 'h2',
  },
  {
    children: [{ text: 'Configure editor plugins' }],
    type: 'h3',
  },
];

BaseHeadingPlugin.configure({ options: { levels: 3 } }) creates H1 through H3. Passing an array such as [1, 3, 5] creates only those levels.

Editing Behavior

All heading levels share the same base behavior.

Input Rules And Shortcuts

HeadingRules.markdown() creates a block-start input rule for the configured plugin key.

The registry kit also binds mod+alt+1 through mod+alt+6 to the matching toggle transform.

Registry UI

Static heading elements preserve an id field by rendering an internal anchor span. That anchor is used by DOCX table-of-contents links.

Markdown

@platejs/markdown maps Markdown heading depth to the matching Plate heading type.

# H1
## H2
### H3

Serialization uses the node type to choose Markdown depth. For example, type: 'h2' serializes as ##.

API Reference