0
# Tiptap Hard Break Extension
1

2
The Tiptap Hard Break Extension provides hard break functionality for rich text editors built with the Tiptap framework. It allows users to insert line breaks (represented as `<br>` HTML elements) within text content using keyboard shortcuts, with configurable options for preserving text marks and customizing HTML attributes.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import { HardBreak } from "@tiptap/extension-hard-break";
15
```
16

17
Default import:
18

19
```typescript
20
import HardBreak from "@tiptap/extension-hard-break";
21
```
22

23
CommonJS:
24

25
```javascript
26
const { HardBreak } = require("@tiptap/extension-hard-break");
27
```
28

29
## Basic Usage
30

31
```typescript
32
import { Editor } from "@tiptap/core";
33
import { HardBreak } from "@tiptap/extension-hard-break";
34

35
const editor = new Editor({
36
  extensions: [
37
    HardBreak.configure({
38
      keepMarks: true,
39
      HTMLAttributes: {
40
        class: 'my-hard-break'
41
      }
42
    })
43
  ],
44
  content: '<p>This is some text.<br>This is on a new line.</p>'
45
});
46

47
// Insert hard break programmatically
48
editor.commands.setHardBreak();
49
```
50

51
## Capabilities
52

53
### Extension Configuration
54

55
The HardBreak extension can be configured with options to control mark preservation and HTML attributes.
56

57
```typescript { .api }
58
const HardBreak: Node<HardBreakOptions>;
59

60
interface HardBreakOptions {
61
  /**
62
   * Controls if marks should be kept after being split by a hard break.
63
   * @default true
64
   */
65
  keepMarks: boolean;
66

67
  /**
68
   * HTML attributes to add to the hard break element.
69
   * @default {}
70
   */
71
  HTMLAttributes: Record<string, any>;
72
}
73
```
74

75
### Commands
76

77
The extension adds a command to insert hard breaks programmatically.
78

79
```typescript { .api }
80
// Command interface extension
81
interface Commands<ReturnType> {
82
  hardBreak: {
83
    /**
84
     * Add a hard break at the current cursor position
85
     */
86
    setHardBreak: () => ReturnType;
87
  };
88
}
89
```
90

91
**Usage Examples:**
92

93
```typescript
94
// Insert hard break using command
95
editor.commands.setHardBreak();
96

97
// Check if command can be executed
98
if (editor.can().setHardBreak()) {
99
  editor.commands.setHardBreak();
100
}
101

102
// Chain with other commands
103
editor.chain()
104
  .insertContent('Some text')
105
  .setHardBreak()
106
  .insertContent('More text')
107
  .run();
108
```
109

110
### Keyboard Shortcuts
111

112
The extension provides built-in keyboard shortcuts for inserting hard breaks.
113

114
**Default Shortcuts:**
115
- `Mod-Enter` (Ctrl/Cmd + Enter) - Insert hard break
116
- `Shift-Enter` - Insert hard break
117

118
### Node Properties
119

120
The HardBreak node has specific properties that define its behavior in the editor.
121

122
```typescript { .api }
123
// Node configuration properties
124
interface NodeConfig {
125
  name: 'hardBreak';
126
  inline: true;
127
  group: 'inline';
128
  selectable: false;
129
  linebreakReplacement: true;
130
}
131
```
132

133
### Extension Methods
134

135
The extension provides core methods for configuration and default values.
136

137
```typescript { .api }
138
/**
139
 * Returns the default options for the HardBreak extension.
140
 * This method defines the baseline configuration that can be overridden via configure().
141
 */
142
addOptions(): HardBreakOptions;
143
```
144

145
**Default Configuration:**
146

147
```typescript
148
// Default options returned by addOptions()
149
{
150
  keepMarks: true,
151
  HTMLAttributes: {}
152
}
153
```
154

155
### HTML Rendering
156

157
The extension handles parsing and rendering of hard break elements.
158

159
```typescript { .api }
160
// HTML parsing configuration
161
parseHTML(): {
162
  tag: 'br';
163
}[];
164

165
// HTML rendering function
166
renderHTML(options: { HTMLAttributes: Record<string, any> }): [
167
  'br',
168
  Record<string, any>
169
];
170

171
// Plain text rendering
172
renderText(): '\n';
173
```
174

175
**Configuration Examples:**
176

177
```typescript
178
// Basic configuration
179
const editor = new Editor({
180
  extensions: [
181
    HardBreak
182
  ]
183
});
184

185
// Custom configuration
186
const editor = new Editor({
187
  extensions: [
188
    HardBreak.configure({
189
      keepMarks: false, // Don't preserve marks after break
190
      HTMLAttributes: {
191
        class: 'custom-break',
192
        'data-type': 'hard-break'
193
      }
194
    })
195
  ]
196
});
197
```
198

199
## Types
200

201
```typescript { .api }
202
/**
203
 * Main extension class created via Node.create<HardBreakOptions>()
204
 */
205
declare const HardBreak: Node<HardBreakOptions>;
206

207
/**
208
 * Configuration options for the HardBreak extension
209
 */
210
interface HardBreakOptions {
211
  /**
212
   * Controls if marks should be kept after being split by a hard break.
213
   * When true, text formatting (bold, italic, etc.) continues after the break.
214
   * @default true
215
   */
216
  keepMarks: boolean;
217

218
  /**
219
   * HTML attributes to add to the hard break element.
220
   * These attributes will be merged with any runtime attributes.
221
   * @default {}
222
   */
223
  HTMLAttributes: Record<string, any>;
224
}
225
```