0
# Tiptap Highlight Extension
1

2
The Tiptap Highlight Extension enables text highlighting functionality in Tiptap rich text editors. It allows users to highlight text selections with customizable background colors, supports both single-color and multi-color highlighting modes, and includes markdown-style input rules for `==text==` syntax.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import { Highlight, inputRegex, pasteRegex } from "@tiptap/extension-highlight";
15
```
16

17
Default import:
18

19
```typescript
20
import Highlight from "@tiptap/extension-highlight";
21
```
22

23
For CommonJS:
24

25
```javascript
26
const { Highlight, inputRegex, pasteRegex } = require("@tiptap/extension-highlight");
27
```
28

29
## Basic Usage
30

31
```typescript
32
import { Editor } from "@tiptap/core";
33
import { Highlight } from "@tiptap/extension-highlight";
34

35
// Basic single-color highlighting
36
const editor = new Editor({
37
  extensions: [
38
    Highlight,
39
  ],
40
});
41

42
// Multi-color highlighting with custom HTML attributes
43
const editor = new Editor({
44
  extensions: [
45
    Highlight.configure({
46
      multicolor: true,
47
      HTMLAttributes: {
48
        class: 'my-highlight',
49
      },
50
    }),
51
  ],
52
});
53

54
// Using highlight commands
55
editor.commands.setHighlight({ color: '#ffc078' });
56
editor.commands.toggleHighlight({ color: '#8ce99a' });
57
editor.commands.unsetHighlight();
58
```
59

60
## Capabilities
61

62
### Extension Configuration
63

64
Configure the Highlight extension with options for multicolor support and HTML attributes.
65

66
```typescript { .api }
67
interface HighlightOptions {
68
  /**
69
   * Allow multiple highlight colors
70
   * @default false
71
   */
72
  multicolor: boolean;
73
  
74
  /**
75
   * HTML attributes to add to the highlight element
76
   * @default {}
77
   */
78
  HTMLAttributes: Record<string, any>;
79
}
80

81
// Highlight is a Mark extension created via Mark.create<HighlightOptions>()
82
// Mark is imported from '@tiptap/core'
83
const Highlight: HighlightExtension;
84
```
85

86
### Highlight Commands
87

88
Programmatic commands for manipulating text highlights, accessible via the editor's command interface.
89

90
```typescript { .api }
91
interface Commands {
92
  highlight: {
93
    /**
94
     * Set a highlight mark on selected text
95
     * @param attributes - Optional highlight attributes
96
     */
97
    setHighlight: (attributes?: { color: string }) => boolean;
98
    
99
    /**
100
     * Toggle a highlight mark on selected text
101
     * @param attributes - Optional highlight attributes
102
     */
103
    toggleHighlight: (attributes?: { color: string }) => boolean;
104
    
105
    /**
106
     * Remove highlight mark from selected text
107
     */
108
    unsetHighlight: () => boolean;
109
  };
110
}
111
```
112

113
**Usage Examples:**
114

115
```typescript
116
// Set highlight with specific color (multicolor mode required)
117
editor.commands.setHighlight({ color: '#ffc078' });
118

119
// Toggle highlight without color (single-color mode)
120
editor.commands.toggleHighlight();
121

122
// Toggle highlight with color (multicolor mode)
123
editor.commands.toggleHighlight({ color: '#8ce99a' });
124

125
// Remove any highlight from selection
126
editor.commands.unsetHighlight();
127
```
128

129
### Input Rules
130

131
Automatic detection and conversion of markdown-style highlight syntax.
132

133
```typescript { .api }
134
/**
135
 * Regex pattern for matching highlight syntax on input
136
 * Matches: ==text== (double equals around text)
137
 */
138
const inputRegex: RegExp; // /(?:^|\s)(==(?!\s+==)((?:[^=]+))==(?!\s+==))$/
139

140
/**
141
 * Regex pattern for matching highlight syntax on paste
142
 * Matches: ==text== (double equals around text, global)
143
 */
144
const pasteRegex: RegExp; // /(?:^|\s)(==(?!\s+==)((?:[^=]+))==(?!\s+==))/g
145
```
146

147
**Usage Examples:**
148

149
```typescript
150
// These patterns are automatically applied when the extension is installed:
151

152
// Typing "==hello world==" will automatically convert to highlighted text
153
// Pasting text with "==highlighted==" syntax will render as highlights
154
```
155

156
### Keyboard Shortcuts
157

158
Built-in keyboard shortcuts for quick highlight operations.
159

160
- **Mod-Shift-h**: Toggle highlight on selected text (uses default color in single-color mode)
161

162
## Types
163

164
```typescript { .api }
165
interface HighlightOptions {
166
  multicolor: boolean;
167
  HTMLAttributes: Record<string, any>;
168
}
169

170
interface HighlightAttributes {
171
  color?: string;
172
}
173

174
// Extension type (created via Mark.create<HighlightOptions>())
175
type HighlightExtension = {
176
  name: 'highlight';
177
  configure: (options?: Partial<HighlightOptions>) => HighlightExtension;
178
};
179

180
// Regex constants
181
const inputRegex: RegExp;
182
const pasteRegex: RegExp;
183
```
184

185
## Architecture
186

187
The Tiptap Highlight Extension follows the standard Tiptap extension pattern:
188

189
- **Mark Extension**: Extends Tiptap's `Mark.create()` to define inline formatting
190
- **HTML Rendering**: Renders as `<mark>` elements with optional color styling
191
- **Command Integration**: Integrates with Tiptap's command system for programmatic control
192
- **Input/Paste Rules**: Automatic markdown-style syntax conversion
193
- **Keyboard Shortcuts**: Built-in shortcuts for common operations
194
- **Multicolor Support**: Optional support for multiple highlight colors with data attributes
195

196
## Error Handling
197

198
The extension follows Tiptap's standard error handling patterns. Commands return boolean values indicating success/failure, and malformed configurations are handled gracefully with fallback to defaults.