Heading

The Heading node provides block-level heading elements (<h1> through <h4> by default). Headings support markdown-style input rules (# + space, ## + space, etc.), keyboard shortcuts, and a toolbar dropdown for switching between heading levels and normal text.

When to use

Choose Heading when you need:

• H1-H6 with configurable allowed levels (default: H1-H4)
• A toolbar dropdown to switch between heading levels and paragraph
• Markdown #, ##, ### shortcuts at the start of a line
• Anchor IDs for deep-linking (pair with UniqueID and TableOfContents)

Skip it if:

• Your editor renders body text only and structural hierarchy lives elsewhere
• You enforce a single H1 at the document level (write a custom node instead)
• You need collapsible sections under headings (use Details instead)

Live Playground

Type # + space, ## + space, ### + space, or #### + space at the start of a line to create headings. Use Mod-Alt-1 through Mod-Alt-4 to toggle heading levels.

Themed

Click to try it out

Headless

The buttons above the editor are custom HTML buttons wired to toggleHeading() and setParagraph(). Active state is tracked with editor.isActive().

Click to try it out

Usage

Heading is included in StarterKit. If you are building a custom setup without StarterKit, add it manually:

Vanilla

import { Document, Text, Paragraph, Heading } from '@domternal/core';
import { DomternalEditor } from '@domternal/vanilla';

const dm = new DomternalEditor(document.getElementById('editor')!, {
  extensions: [Document, Text, Paragraph, Heading],
  content: '<h1>Hello world</h1><p>Some text</p>',
});

Angular

import { Component, signal } from '@angular/core';
import { DomternalEditorComponent } from '@domternal/angular';
import { Editor, Document, Text, Paragraph, Heading } from '@domternal/core';

@Component({
  selector: 'app-editor',
  imports: [DomternalEditorComponent],
  template: `
    <domternal-editor
      [extensions]="extensions"
      [content]="content"
      (editorCreated)="editor.set($event)"
    />
  `,
})
export class EditorComponent {
  editor = signal<Editor | null>(null);
  extensions = [Document, Text, Paragraph, Heading];
  content = '<h1>Hello world</h1><p>Some text</p>';
}

React

import { Domternal } from '@domternal/react';
import { Document, Text, Paragraph, Heading } from '@domternal/core';

export default function Editor() {
  return (
    <Domternal
      extensions={[Document, Text, Paragraph, Heading]}
      content="<h1>Hello world</h1><p>Some text</p>"
    >
      <Domternal.Content />
    </Domternal>
  );
}

Vue

<script setup lang="ts">
import { Domternal } from '@domternal/vue';
import { Document, Text, Paragraph, Heading } from '@domternal/core';

const extensions = [Document, Text, Paragraph, Heading];
</script>

<template>
  <Domternal :extensions="extensions" content="<h1>Hello world</h1><p>Some text</p>">
    <Domternal.Content />
  </Domternal>
</template>

Schema

Property	Value
ProseMirror name	heading
Type	Node
Group	block
Content	inline* (zero or more inline nodes)
Defining	Yes
HTML tag	<h1> through <h4> (based on level)

The defining property means that when you select a heading and paste content over it, the replacement keeps the heading type rather than converting to the pasted node type.

Options

Option	Type	Default	Description
levels	number[]	[1, 2, 3, 4]	Which heading levels to allow
HTMLAttributes	Record<string, unknown>	{}	HTML attributes added to the heading element

Custom heading levels

import { Heading } from '@domternal/core';

// Only allow h1 and h2
const CustomHeading = Heading.configure({
  levels: [1, 2],
});

This restricts both the input rules and keyboard shortcuts to only the configured levels. For example, ### + space would not trigger a heading conversion if level 3 is not included.

You can also widen past the default. Heading.configure({ levels: [1, 2, 3, 4, 5, 6] }) gives you a working schema, HTML parsing and rendering, input rules (##### + space, ###### + space) and keyboard shortcuts (Mod-Alt-5, Mod-Alt-6) for the extra levels. @domternal/theme applies its shared heading rules (line height, block inline padding) to h5 and h6 as well, and both carry a size: h5 at 1em and h6 at 0.9em with a muted color, continuing the ladder from h3 (1.25em) and h4 (1.1em). h5 used to have no rule at all, which left it on the browser default of 0.83em, so it rendered SMALLER than h6 and smaller than body text. That was an omission rather than a design, and it stayed invisible because the extension ships with levels 1 to 4.

What you do not get is menu surface area. The toolbar heading dropdown renders levels 1-4 only, and the slash / floating menu renders levels 1-3 only, so H5 and H6 are reachable through input rules, keyboard shortcuts and the commands API (setHeading({ level: 5 })) but never appear in a menu. With the caret inside an H5 or H6 the dropdown also has no matching item to highlight, so its dynamicIcon trigger falls back to the generic textH icon.

Custom HTML attributes

import { Heading } from '@domternal/core';

const CustomHeading = Heading.configure({
  HTMLAttributes: { class: 'my-heading' },
});

Attributes

Attribute	Type	Default	Description
level	number	1	The heading level (1-4)

The level attribute is parsed from the HTML tag name (<h1> = level 1, <h2> = level 2, etc.) and is not rendered as an HTML attribute. Instead, it determines which tag is used in the output.

Commands

Command	Description
setHeading({ level })	Convert the current block to a heading at the given level
toggleHeading({ level })	Toggle between heading and paragraph

// Convert the current block to an h2
editor.commands.setHeading({ level: 2 });

// Toggle between h1 and paragraph
editor.commands.toggleHeading({ level: 1 });

// With chaining
editor.chain().focus().toggleHeading({ level: 3 }).run();

setHeading returns false if the requested level is not in the configured levels array. toggleHeading converts a heading back to a paragraph if the current block is already a heading at that level.

Keyboard shortcuts

Shortcut	Cursor position	Command
Mod-Alt-1	any	toggleHeading({ level: 1 })
Mod-Alt-2	any	toggleHeading({ level: 2 })
Mod-Alt-3	any	toggleHeading({ level: 3 })
Mod-Alt-4	any	toggleHeading({ level: 4 })
Enter	End of heading, non-empty	Insert paragraph as next sibling (NEW v0.7.0)
Enter	Empty heading	Convert in place to paragraph (NEW v0.7.0)
Enter	Mid/start of heading	Default split - both halves stay heading
Backspace	Start of heading	Convert heading to paragraph

Shortcuts are generated dynamically from the levels option. If you configure levels: [1, 2], only Mod-Alt-1 and Mod-Alt-2 are registered.

Notion-style Enter behavior (v0.7.0)

The Enter key now has Notion-style behavior that runs BEFORE BaseKeymap:

1. End of a non-empty heading: Inserts a new paragraph as the next sibling and moves the caret into it. No need to type a manual paragraph after a heading.
2. Empty heading: Converts the heading IN PLACE to a paragraph (no extra block created). Useful for exiting an accidental # input rule with a single keystroke.
3. Middle or start of a non-empty heading: Default split - the text after the cursor moves into a new heading of the same level.

The schema is validated before insertion: parent must accept paragraph at the position. This avoids breaking nested-in-listItem cases where the parent doesn’t allow paragraph siblings.

Backspace behavior

The Backspace behavior converts a heading to a paragraph when the cursor is at position 0 inside the heading and the selection is empty. This lets users easily “undo” a heading by pressing backspace at the beginning of the line. Parity with the Enter behavior above.

/h1 inside a list-item label (v0.7.0)

When a user types /h1 (slash command) in a list-item label and selects “Heading 1”, the item dissolves via a setBlockType lift fallback. This prevents an awkward “heading inside listItem label paragraph” state and matches Notion’s behavior.

Input rules

Input	Result
# + space	Heading level 1
## + space	Heading level 2
### + space	Heading level 3
#### + space	Heading level 4

Type the hash characters at the start of a new line, then press space. The line converts to a heading at the matching level. Only levels included in the levels option are recognized.

Toolbar items

Main toolbar

Heading registers a dropdown in the toolbar with the name heading in group blocks at priority 200.

The dropdown contains:

Item	Command	Icon	Shortcut
Normal text	setParagraph	textT	Mod-Alt-0
Heading 1	toggleHeading({ level: 1 })	textHOne	Mod-Alt-1
Heading 2	toggleHeading({ level: 2 })	textHTwo	Mod-Alt-2
Heading 3	toggleHeading({ level: 3 })	textHThree	Mod-Alt-3
Heading 4	toggleHeading({ level: 4 })	textHFour	Mod-Alt-4

The dropdown uses dynamicIcon: true, which means the dropdown button icon changes to match the currently active heading level.

Slash / floating menu

Heading also registers items in the Basic group of the slash command and floating menu, matched by the keywords heading, h<n> and title:

Item	Label	Description	Icon	Shortcut hint	Priority
heading-1	Heading 1	Big section heading	textHOne	#	200
heading-2	Heading 2	Medium section heading	textHTwo	##	190
heading-3	Heading 3	Small section heading	textHThree	###	180

All three run toggleHeading({ level }). Priorities come from 210 - level * 10, so lower levels sort first. Only levels 1-3 appear here: level 4 is enabled by default but stays toolbar-only, and configuring higher levels does not add them either.

JSON representation

{
  "type": "heading",
  "attrs": { "level": 2 },
  "content": [
    { "type": "text", "text": "Hello world" }
  ]
}

An empty heading:

{
  "type": "heading",
  "attrs": { "level": 1 }
}

Source

@domternal/core - Heading.ts

See also

• Paragraph - default block-level text container
• Text Align - paragraph and heading text alignment
• Table Of Contents - auto-generated table of contents from headings
• Unique Id - stable IDs on block nodes for anchoring