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.