Heading

---
title: Heading
docs:
  - route: /docs/components/heading-node
    title: Heading Element
---

<ComponentPreview name="basic-blocks-demo" />

<PackageInfo>

## Features

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

</PackageInfo>

## Kit Usage

<Steps>

### 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](/docs/installation/plate-ui) components.

<ComponentSource name="basic-blocks-kit" />

- [`H1Element`](/docs/components/heading-node): Renders H1 elements.
- [`H2Element`](/docs/components/heading-node): Renders H2 elements.
- [`H3Element`](/docs/components/heading-node): Renders H3 elements.

### Add Kit

Add the kit to your plugins:

```tsx
import { createPlateEditor } from 'platejs/react';
import { BasicBlocksKit } from '@/components/editor/plugins/basic-blocks-kit';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    ...BasicBlocksKit,
  ],
});
```

</Steps>

## Manual Usage

<Steps>

### Installation

```bash
npm install @platejs/basic-nodes
```

### Add Plugins

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

```tsx
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.

```tsx
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`](/docs/components/heading-node) to render the specific heading level.
- `shortcuts.toggle`: Defines a keyboard [shortcut](/docs/plugin-shortcuts) (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](/docs/toolbar#turn-into-toolbar-button) to convert blocks into headings:

```tsx
{
  icon: <Heading1Icon />,
  label: 'Heading 1',
  value: 'h1',
}
```

```tsx
{
  icon: <Heading2Icon />,
  label: 'Heading 2',
  value: 'h2',
}
```

```tsx
{
  icon: <Heading3Icon />,
  label: 'Heading 3',
  value: 'h3',
}
```

### Insert Toolbar Button

You can add these items to the [Insert Toolbar Button](/docs/toolbar#insert-toolbar-button) to insert heading elements:

```tsx
{
  icon: <Heading1Icon />,
  label: 'Heading 1',
  value: 'h1',
}
```

```tsx
{
  icon: <Heading2Icon />,
  label: 'Heading 2',
  value: 'h2',
}
```

```tsx
{
  icon: <Heading3Icon />,
  label: 'Heading 3',
  value: 'h3',
}
```

</Steps>

## 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.