0
# Tiptap Horizontal Rule Extension
1
2
The Tiptap Horizontal Rule Extension provides functionality to insert horizontal rule elements (`<hr>`) in Tiptap editors. It integrates seamlessly with the Tiptap ecosystem as a block-level node extension with automatic input rules and editor commands.
3
4
## Package Information
5
6
- **Package Name**: @tiptap/extension-horizontal-rule
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @tiptap/extension-horizontal-rule`
10
11
## Core Imports
12
13
```typescript
14
import { HorizontalRule } from "@tiptap/extension-horizontal-rule";
15
```
16
17
For CommonJS:
18
19
```javascript
20
const { HorizontalRule } = require("@tiptap/extension-horizontal-rule");
21
```
22
23
Default export:
24
25
```typescript
26
import HorizontalRule from "@tiptap/extension-horizontal-rule";
27
```
28
29
## Basic Usage
30
31
```typescript
32
import { Editor } from "@tiptap/core";
33
import { HorizontalRule } from "@tiptap/extension-horizontal-rule";
34
35
// Create editor with HorizontalRule extension
36
const editor = new Editor({
37
extensions: [
38
HorizontalRule.configure({
39
HTMLAttributes: {
40
class: "my-horizontal-rule",
41
},
42
}),
43
],
44
});
45
46
// Insert horizontal rule programmatically
47
editor.commands.setHorizontalRule();
48
49
// Input rules: Type these patterns to auto-insert horizontal rules
50
// --- (three hyphens)
51
// —- (em dash + hyphen)
52
// ___ (three underscores + space)
53
// *** (three asterisks + space)
54
```
55
56
## Capabilities
57
58
### Extension Class
59
60
The main extension class that registers the horizontal rule node with Tiptap.
61
62
```typescript { .api }
63
/**
64
* Tiptap node extension that allows inserting horizontal rules
65
* Created using Node.create<HorizontalRuleOptions>()
66
*/
67
const HorizontalRule: Node<HorizontalRuleOptions>;
68
```
69
70
### Configuration Options
71
72
Options interface for configuring the HorizontalRule extension.
73
74
```typescript { .api }
75
interface HorizontalRuleOptions {
76
/**
77
* The HTML attributes for a horizontal rule node.
78
* @default {}
79
* @example { class: 'foo' }
80
*/
81
HTMLAttributes: Record<string, any>;
82
}
83
```
84
85
### Editor Commands
86
87
Command to insert a horizontal rule at the current cursor position. This command is added to the Tiptap editor instance via TypeScript module augmentation.
88
89
```typescript { .api }
90
/**
91
* Add a horizontal rule at the current cursor position
92
* Available via editor.commands.setHorizontalRule()
93
* @example editor.commands.setHorizontalRule()
94
*/
95
function setHorizontalRule(): boolean;
96
```
97
98
**Usage Examples:**
99
100
```typescript
101
// Basic insertion
102
editor.commands.setHorizontalRule();
103
104
// Check if command can execute
105
if (editor.can().setHorizontalRule()) {
106
editor.commands.setHorizontalRule();
107
}
108
109
// Chain with other commands
110
editor
111
.chain()
112
.focus()
113
.setHorizontalRule()
114
.insertContent({ type: 'paragraph' })
115
.run();
116
```
117
118
### Input Rules
119
120
Automatic text patterns that trigger horizontal rule insertion when typed.
121
122
The extension automatically converts these patterns to horizontal rules:
123
124
- `---` - Three consecutive hyphens
125
- `—-` - Em dash followed by hyphen
126
- `___ ` - Three underscores followed by space
127
- `*** ` - Three asterisks followed by space
128
129
The input rules are created internally using the `nodeInputRule` function from `@tiptap/core` with the regex pattern `/^(?:---|—-|___\s|\*\*\*\s)$/` which matches:
130
- `---` at start of line (three hyphens)
131
- `—-` at start of line (em dash + hyphen)
132
- `___ ` at start of line (three underscores + space)
133
- `*** ` at start of line (three asterisks + space)
134
135
### Extension Properties
136
137
Key properties and methods of the HorizontalRule extension.
138
139
```typescript { .api }
140
interface HorizontalRuleExtension {
141
/** Extension name */
142
name: "horizontalRule";
143
/** Node group classification */
144
group: "block";
145
/** Default options */
146
addOptions(): HorizontalRuleOptions;
147
/** HTML parsing configuration */
148
parseHTML(): Array<{ tag: string }>;
149
/** HTML rendering method */
150
renderHTML(props: { HTMLAttributes: Record<string, any> }): [string, Record<string, any>];
151
/** Command definitions */
152
addCommands(): Record<string, () => any>;
153
/** Input rule definitions */
154
addInputRules(): any[];
155
}
156
```
157
158
## HTML Output
159
160
Horizontal rules are rendered as `<hr>` elements. The final HTML attributes are merged from:
161
162
1. Extension configuration (`HTMLAttributes` option)
163
2. Runtime attributes passed to the render function
164
165
```html
166
<!-- Default output -->
167
<hr>
168
169
<!-- With custom attributes -->
170
<hr class="custom-hr" data-type="divider">
171
```
172
173
## Integration Notes
174
175
### Extension Registration
176
177
The extension must be registered with a Tiptap editor instance:
178
179
```typescript
180
import { Editor } from "@tiptap/core";
181
import { HorizontalRule } from "@tiptap/extension-horizontal-rule";
182
183
const editor = new Editor({
184
extensions: [
185
HorizontalRule,
186
// other extensions...
187
],
188
});
189
```
190
191
### Cursor Positioning
192
193
When a horizontal rule is inserted:
194
195
1. The cursor automatically moves to the position after the horizontal rule
196
2. If the horizontal rule is at the document end, a new paragraph is created
197
3. The view scrolls to keep the cursor visible
198
199
### Schema Integration
200
201
- **Node Type**: Block-level element
202
- **Content Model**: Empty (self-closing)
203
- **Atom**: True (cannot contain other content)
204
- **Selectable**: True (can be selected as a node)
205
206
## Dependencies
207
208
Required peer dependencies:
209
210
- `@tiptap/core` - Core Tiptap functionality
211
- `@tiptap/pm` - ProseMirror integration layer
212
213
These must be installed separately and are not bundled with the extension.