0
# TipTap Heading Extension
1

2
The TipTap Heading Extension provides HTML heading functionality (h1-h6) for TipTap rich text editors. It includes configurable heading levels, keyboard shortcuts, markdown-style input rules, and programmatic commands for setting and toggling headings.
3

4
## Package Information
5

6
- **Package Name**: @tiptap/extension-heading
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @tiptap/extension-heading`
10

11
## Core Imports
12

13
```typescript
14
import { Heading } from "@tiptap/extension-heading";
15
```
16

17
Default import:
18
```typescript
19
import Heading from "@tiptap/extension-heading";
20
```
21

22
Named imports:
23
```typescript
24
import { Heading, Level, HeadingOptions } from "@tiptap/extension-heading";
25
```
26

27
CommonJS:
28
```javascript
29
const { Heading } = require("@tiptap/extension-heading");
30
```
31

32
## Basic Usage
33

34
```typescript
35
import { Editor } from "@tiptap/core";
36
import { Heading } from "@tiptap/extension-heading";
37

38
// Create editor with heading extension
39
const editor = new Editor({
40
  extensions: [
41
    Heading.configure({
42
      levels: [1, 2, 3, 4, 5, 6], // Allow all heading levels
43
      HTMLAttributes: {
44
        class: 'my-heading',
45
      },
46
    }),
47
  ],
48
});
49

50
// Use commands programmatically
51
editor.commands.setHeading({ level: 1 }); // Set to h1
52
editor.commands.toggleHeading({ level: 2 }); // Toggle h2
53

54
// Keyboard shortcuts work automatically:
55
// Mod-Alt-1 through Mod-Alt-6 toggle heading levels
56

57
// Markdown input rules work automatically:
58
// Type "# " for h1, "## " for h2, etc.
59
```
60

61
## Capabilities
62

63
### Heading Extension Configuration
64

65
Creates a configurable heading node extension for TipTap editors with support for h1-h6 HTML elements.
66

67
```typescript { .api }
68
import { Node } from "@tiptap/core";
69

70
/**
71
 * Main heading extension that provides h1-h6 functionality
72
 */
73
const Heading: Node<HeadingOptions>;
74

75
/**
76
 * Configuration options for the heading extension
77
 */
78
interface HeadingOptions {
79
  /**
80
   * Array of allowed heading levels (1-6)
81
   * @default [1, 2, 3, 4, 5, 6]
82
   */
83
  levels: Level[];
84
  
85
  /**
86
   * HTML attributes applied to all heading elements
87
   * @default {}
88
   */
89
  HTMLAttributes: Record<string, any>;
90
}
91

92
/**
93
 * Valid heading levels corresponding to h1-h6 HTML elements
94
 */
95
type Level = 1 | 2 | 3 | 4 | 5 | 6;
96
```
97

98
### Set Heading Command
99

100
Programmatically sets the current selection to a heading with the specified level.
101

102
```typescript { .api }
103
/**
104
 * Sets current selection to a heading node with specified level
105
 * @param attributes Object containing the heading level
106
 * @returns Command execution result
107
 */
108
editor.commands.setHeading(attributes: { level: Level }): boolean;
109
```
110

111
**Usage Example:**
112
```typescript
113
// Set current line/selection to h1
114
editor.commands.setHeading({ level: 1 });
115

116
// Set to h3
117
editor.commands.setHeading({ level: 3 });
118
```
119

120
### Toggle Heading Command
121

122
Toggles between a heading of the specified level and a paragraph, or changes between heading levels.
123

124
```typescript { .api }
125
/**
126
 * Toggles between heading and paragraph, or changes heading level
127
 * @param attributes Object containing the heading level to toggle
128
 * @returns Command execution result
129
 */
130
editor.commands.toggleHeading(attributes: { level: Level }): boolean;
131
```
132

133
**Usage Example:**
134
```typescript
135
// Toggle h2 - if current node is h2, converts to paragraph
136
// If current node is paragraph or other heading, converts to h2
137
editor.commands.toggleHeading({ level: 2 });
138

139
// Toggle h1
140
editor.commands.toggleHeading({ level: 1 });
141
```
142

143
### Keyboard Shortcuts
144

145
The extension automatically registers keyboard shortcuts for each configured heading level:
146

147
- **Mod-Alt-1**: Toggle h1 heading
148
- **Mod-Alt-2**: Toggle h2 heading  
149
- **Mod-Alt-3**: Toggle h3 heading
150
- **Mod-Alt-4**: Toggle h4 heading
151
- **Mod-Alt-5**: Toggle h5 heading
152
- **Mod-Alt-6**: Toggle h6 heading
153

154
**Note**: `Mod` key is Cmd on Mac and Ctrl on Windows/Linux.
155

156
### Input Rules
157

158
The extension supports markdown-style input for creating headings:
159

160
- Type `# ` (hash + space) to create h1
161
- Type `## ` (two hashes + space) to create h2  
162
- Type `### ` (three hashes + space) to create h3
163
- Continue pattern up to `###### ` for h6
164

165
The input rules create patterns for each configured heading level, where the exact number of hashes corresponds to the heading level (h1=1 hash, h2=2 hashes, etc.).
166

167
## Configuration Examples
168

169
### Restrict to Specific Levels
170

171
```typescript
172
// Only allow h1, h2, and h3
173
const editor = new Editor({
174
  extensions: [
175
    Heading.configure({
176
      levels: [1, 2, 3],
177
    }),
178
  ],
179
});
180
```
181

182
### Add Custom HTML Attributes
183

184
```typescript
185
// Add CSS classes and other attributes
186
const editor = new Editor({
187
  extensions: [
188
    Heading.configure({
189
      levels: [1, 2, 3, 4, 5, 6],
190
      HTMLAttributes: {
191
        class: 'prose-heading',
192
        'data-heading': 'true',
193
      },
194
    }),
195
  ],
196
});
197
```
198

199
### Documentation Headings Only
200

201
```typescript
202
// Configure for documentation with h1-h4 only
203
const editor = new Editor({
204
  extensions: [
205
    Heading.configure({
206
      levels: [1, 2, 3, 4],
207
      HTMLAttributes: {
208
        class: 'doc-heading',
209
      },
210
    }),
211
  ],
212
});
213
```
214

215
## Integration Notes
216

217
- **TipTap Core**: Requires `@tiptap/core` as a peer dependency
218
- **ProseMirror Schema**: Creates heading nodes in the ProseMirror document schema
219
- **HTML Rendering**: Renders as semantic h1-h6 HTML elements
220
- **Block Element**: Functions as a block-level element that can contain inline content
221
- **Accessibility**: Maintains proper heading semantics for screen readers and SEO