Heading

PreviousNext
Heading Element
Loading...
Files
components/demo.tsx
'use client';

import * as React from 'react';

import { Plate, usePlateEditor } from 'platejs/react';

import { EditorKit } from '@/components/editor/editor-kit';
import { Editor, EditorContainer } from '@/components/ui/editor';

import { DEMO_VALUES } from './values/demo-values';

export default function Demo({ id }: { id: string }) {
  const editor = usePlateEditor({
    plugins: EditorKit,
    value: DEMO_VALUES[id],
  });

  return (
    <Plate editor={editor}>
      <EditorContainer variant="demo">
        <Editor />
      </EditorContainer>
    </Plate>
  );
}

Features

  • Create headings of various levels (H1 to H6) to structure content.
  • Renders as appropriate HTML heading tags (<h1> to <h6>) by default.

Kit Usage

Installation

The fastest way to add heading plugins is with the BasicBlocksKit, which includes pre-configured H1Plugin, H2Plugin, and H3Plugin along with other basic block elements and their Plate UI components.

'use client';
 
import {
  BlockquotePlugin,
  H1Plugin,
  H2Plugin,
  H3Plugin,
  HorizontalRulePlugin,
} from '@platejs/basic-nodes/react';
import { ParagraphPlugin } from 'platejs/react';
 
import { BlockquoteElement } from '@/components/ui/blockquote-node';
import { H1Element, H2Element, H3Element } from '@/components/ui/heading-node';
import { HrElement } from '@/components/ui/hr-node';
import { ParagraphElement } from '@/components/ui/paragraph-node';
 
export const BasicBlocksKit = [
  ParagraphPlugin.withComponent(ParagraphElement),
  H1Plugin.configure({
    node: {
      component: H1Element,
    },
    rules: {
      break: { empty: 'reset' },
    },
    shortcuts: { toggle: { keys: 'mod+alt+1' } },
  }),
  H2Plugin.configure({
    node: {
      component: H2Element,
    },
    rules: {
      break: { empty: 'reset' },
    },
    shortcuts: { toggle: { keys: 'mod+alt+2' } },
  }),
  H3Plugin.configure({
    node: {
      component: H3Element,
    },
    rules: {
      break: { empty: 'reset' },
    },
    shortcuts: { toggle: { keys: 'mod+alt+3' } },
  }),
  BlockquotePlugin.configure({
    node: { component: BlockquoteElement },
    shortcuts: { toggle: { keys: 'mod+shift+period' } },
  }),
  HorizontalRulePlugin.withComponent(HrElement),
];

Add Kit

Add the kit to your plugins:

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

Manual Usage

Installation

pnpm add @platejs/basic-nodes

Add Plugins

Add individual heading plugins when you need more control or want to include specific heading levels.

import { createPlateEditor } from 'platejs/react';
import { H1Plugin, H2Plugin, H3Plugin } from '@platejs/basic-nodes/react';
 
const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    H1Plugin,
    H2Plugin,
    H3Plugin,
    // Add H4Plugin, H5Plugin, H6Plugin as needed
  ],
});

Configure Plugins

Configure individual heading plugins with custom components or shortcuts.

import { createPlateEditor } from 'platejs/react';
import { H1Plugin, H2Plugin, H3Plugin } from '@platejs/basic-nodes/react';
import { H1Element, H2Element, H3Element } from '@/components/ui/heading-node';
 
const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    H1Plugin.configure({
      node: { component: H1Element },
      shortcuts: { toggle: { keys: 'mod+alt+1' } },
    }),
    H2Plugin.configure({
      node: { component: H2Element },
      shortcuts: { toggle: { keys: 'mod+alt+2' } },
    }),
    H3Plugin.configure({
      node: { component: H3Element },
      shortcuts: { toggle: { keys: 'mod+alt+3' } },
    }),
    // Configure H4Plugin, H5Plugin, H6Plugin similarly
  ],
});
  • node.component: Assigns a custom React component like H1Element to render the specific heading level.
  • shortcuts.toggle: Defines a keyboard shortcut (e.g., mod+alt+1) to toggle the respective heading level.

Turn Into Toolbar Button

You can add these items to the Turn Into Toolbar Button to convert blocks into headings:

{
  icon: <Heading1Icon />,
  label: 'Heading 1',
  value: 'h1',
}
{
  icon: <Heading2Icon />,
  label: 'Heading 2',
  value: 'h2',
}
{
  icon: <Heading3Icon />,
  label: 'Heading 3',
  value: 'h3',
}

Insert Toolbar Button

You can add these items to the Insert Toolbar Button to insert heading elements:

{
  icon: <Heading1Icon />,
  label: 'Heading 1',
  value: 'h1',
}
{
  icon: <Heading2Icon />,
  label: 'Heading 2',
  value: 'h2',
}
{
  icon: <Heading3Icon />,
  label: 'Heading 3',
  value: 'h3',
}

Plugins

H1Plugin

Plugin for H1 heading elements.

H2Plugin

Plugin for H2 heading elements.

H3Plugin

Plugin for H3 heading elements.

H4Plugin

Plugin for H4 heading elements.

H5Plugin

Plugin for H5 heading elements.

H6Plugin

Plugin for H6 heading elements.

Transforms

tf.h1.toggle

Toggles the selected block types to heading.

BlockquoteHorizontal Rule