0
# Tiptap Extension Underline
1

2
The @tiptap/extension-underline package provides underline text formatting functionality for Tiptap editors. This extension adds underline mark support with keyboard shortcuts, commands, and HTML parsing/rendering capabilities.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript { .api }
14
import { Underline } from "@tiptap/extension-underline";
15
```
16

17
Default import:
18

19
```typescript { .api }
20
import Underline from "@tiptap/extension-underline";
21
```
22

23
For named imports with types:
24

25
```typescript { .api }
26
import { Underline, UnderlineOptions } from "@tiptap/extension-underline";
27
```
28

29
Mixed imports (default + named):
30

31
```typescript { .api }
32
import Underline, { UnderlineOptions } from "@tiptap/extension-underline";
33
```
34

35
CommonJS:
36

37
```javascript { .api }
38
const { Underline } = require("@tiptap/extension-underline");
39
```
40

41
CommonJS default:
42

43
```javascript { .api }
44
const Underline = require("@tiptap/extension-underline").default;
45
```
46

47
## Basic Usage
48

49
```typescript
50
import { Editor } from "@tiptap/core";
51
import { Underline } from "@tiptap/extension-underline";
52

53
// Add underline extension to editor
54
const editor = new Editor({
55
  extensions: [
56
    Underline,
57
    // other extensions...
58
  ],
59
});
60

61
// Use commands to apply underline formatting
62
editor.commands.setUnderline();      // Apply underline
63
editor.commands.toggleUnderline();   // Toggle underline
64
editor.commands.unsetUnderline();    // Remove underline
65

66
// Check if text is underlined
67
const isUnderlined = editor.isActive('underline');
68
```
69

70
## Architecture
71

72
The underline extension follows Tiptap's standard mark extension pattern:
73

74
- **Mark Extension**: Extends the base `Mark` class from `@tiptap/core`
75
- **Command Integration**: Registers commands with the editor's command system
76
- **HTML Processing**: Handles parsing and rendering of underline HTML elements
77
- **Keyboard Shortcuts**: Provides `Mod-u` and `Mod-U` shortcuts for toggling underline
78
- **Type Safety**: Full TypeScript support with proper type definitions
79

80
## Capabilities
81

82
### Extension Configuration
83

84
Configure the underline extension with custom HTML attributes.
85

86
```typescript { .api }
87
interface UnderlineOptions {
88
  /**
89
   * HTML attributes to add to the underline element.
90
   * @default {}
91
   * @example { class: 'foo' }
92
   */
93
  HTMLAttributes: Record<string, any>;
94
}
95
```
96

97
Usage with custom options:
98

99
```typescript
100
import { Underline } from "@tiptap/extension-underline";
101

102
const editor = new Editor({
103
  extensions: [
104
    Underline.configure({
105
      HTMLAttributes: {
106
        class: 'custom-underline',
107
        'data-type': 'emphasis',
108
      },
109
    }),
110
  ],
111
});
112
```
113

114
### Underline Extension
115

116
The main extension class that provides underline functionality.
117

118
```typescript { .api }
119
/**
120
 * This extension allows you to create underline text.
121
 * @see https://www.tiptap.dev/api/marks/underline
122
 */
123
const Underline: Mark<UnderlineOptions>;
124
```
125

126
### Commands
127

128
The extension adds the following commands to the editor's command interface:
129

130
#### Set Underline
131

132
Apply underline mark to the current selection.
133

134
```typescript { .api }
135
/**
136
 * Set an underline mark
137
 * @example editor.commands.setUnderline()
138
 */
139
setUnderline(): boolean;
140
```
141

142
#### Toggle Underline
143

144
Toggle underline mark on the current selection.
145

146
```typescript { .api }
147
/**
148
 * Toggle an underline mark  
149
 * @example editor.commands.toggleUnderline()
150
 */
151
toggleUnderline(): boolean;
152
```  
153

154
#### Unset Underline
155

156
Remove underline mark from the current selection.
157

158
```typescript { .api }
159
/**
160
 * Unset an underline mark
161
 * @example editor.commands.unsetUnderline()
162
 */
163
unsetUnderline(): boolean;
164
```
165

166
### Keyboard Shortcuts
167

168
The extension provides built-in keyboard shortcuts:
169

170
- **Mod-u**: Toggle underline (Ctrl-u on Windows/Linux, Cmd-u on Mac)
171
- **Mod-U**: Toggle underline (Ctrl-Shift-u on Windows/Linux, Cmd-Shift-u on Mac)
172

173
### HTML Processing
174

175
The extension handles HTML parsing and rendering:
176

177
**HTML Parsing**: Recognizes the following HTML as underline marks:
178
- `<u>` tags
179
- Elements with `text-decoration: underline` CSS style
180

181
**HTML Rendering**: Outputs underlined text as:
182
```html
183
<u>underlined text</u>
184
```
185

186
With custom HTML attributes:
187
```html
188
<u class="custom-underline" data-type="emphasis">underlined text</u>
189
```
190

191
## Types
192

193
```typescript { .api }
194
/**
195
 * Configuration options for the underline extension
196
 */
197
interface UnderlineOptions {
198
  /**
199
   * HTML attributes to add to the underline element.
200
   * @default {}
201
   */
202
  HTMLAttributes: Record<string, any>;
203
}
204

205
/**
206
 * Underline extension commands added to the editor
207
 */
208
interface Commands<ReturnType> {
209
  underline: {
210
    setUnderline: () => ReturnType;
211
    toggleUnderline: () => ReturnType;
212
    unsetUnderline: () => ReturnType;
213
  };
214
}
215
```
216

217
## Usage Examples
218

219
### Basic Text Formatting
220

221
```typescript
222
import { Editor } from "@tiptap/core";
223
import { Underline } from "@tiptap/extension-underline";
224

225
const editor = new Editor({
226
  extensions: [Underline],
227
  content: '<p>This text has <u>underlined</u> content.</p>',
228
});
229

230
// Apply underline to current selection
231
editor.commands.setUnderline();
232

233
// Check if current selection is underlined
234
if (editor.isActive('underline')) {
235
  console.log('Text is underlined');
236
}
237
```
238

239
### Custom Styling
240

241
```typescript
242
const editor = new Editor({
243
  extensions: [
244
    Underline.configure({
245
      HTMLAttributes: {
246
        class: 'fancy-underline',
247
        style: 'text-decoration-color: blue;',
248
      },
249
    }),
250
  ],
251
});
252
```
253

254
### Programmatic Control
255

256
```typescript
257
// Toggle underline on button click
258
document.getElementById('underline-button')?.addEventListener('click', () => {
259
  editor.commands.toggleUnderline();
260
});
261

262
// Remove all underline formatting
263
document.getElementById('clear-underline')?.addEventListener('click', () => {
264
  editor.commands.unsetUnderline();
265
});
266
```