0
# Tiptap Link Extension
1

2
The @tiptap/extension-link package provides comprehensive link functionality for the Tiptap rich text editor. It includes automatic link detection as users type, intelligent paste handling that converts pasted URLs into links, customizable click behavior with optional link opening, and robust XSS protection through URL validation.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import { Link } from "@tiptap/extension-link";
15
```
16

17
All exports are also available as named imports:
18

19
```typescript
20
import { 
21
  Link, 
22
  isAllowedUri, 
23
  pasteRegex, 
24
  LinkOptions, 
25
  LinkProtocolOptions,
26
  UNICODE_WHITESPACE_PATTERN,
27
  UNICODE_WHITESPACE_REGEX,
28
  UNICODE_WHITESPACE_REGEX_END,
29
  UNICODE_WHITESPACE_REGEX_GLOBAL
30
} from "@tiptap/extension-link";
31
```
32

33
CommonJS:
34

35
```javascript
36
const { Link } = require("@tiptap/extension-link");
37
```
38

39
## Basic Usage
40

41
```typescript
42
import { Editor } from "@tiptap/core";
43
import { Link } from "@tiptap/extension-link";
44

45
// Create editor with Link extension
46
const editor = new Editor({
47
  extensions: [
48
    Link.configure({
49
      openOnClick: true,
50
      autolink: true,
51
      linkOnPaste: true,
52
      HTMLAttributes: {
53
        target: "_blank",
54
        rel: "noopener noreferrer nofollow",
55
      },
56
    }),
57
  ],
58
  content: '<p>Type or paste a URL like https://tiptap.dev to see automatic linking!</p>',
59
});
60

61
// Programmatically set links
62
editor.commands.setLink({ href: "https://tiptap.dev" });
63

64
// Toggle links
65
editor.commands.toggleLink({ href: "https://example.com" });
66

67
// Remove links
68
editor.commands.unsetLink();
69
```
70

71
## Architecture
72

73
The Link extension is built around several key components:
74

75
- **Link Mark**: ProseMirror mark-based link implementation with HTML attribute support
76
- **Command System**: Chainable commands for link manipulation (setLink, toggleLink, unsetLink)
77
- **Plugin System**: Multiple ProseMirror plugins for autolink, click handling, and paste processing
78
- **XSS Protection**: URI validation system preventing malicious links
79
- **Protocol Support**: Custom protocol registration beyond standard http/https
80
- **Helper Modules**: Specialized modules for autolink detection, click handling, paste processing, and whitespace handling
81

82
## Capabilities
83

84
### Link Extension Configuration
85

86
Core Link extension class with comprehensive configuration options for behavior, validation, and appearance customization.
87

88
```typescript { .api }
89
const Link: Mark<LinkOptions>;
90

91
interface LinkOptions {
92
  /** Enable automatic link creation as you type */
93
  autolink: boolean;
94
  /** Custom protocols to register with linkifyjs */
95
  protocols: Array<LinkProtocolOptions | string>;
96
  /** Default protocol when none specified */
97
  defaultProtocol: string;
98
  /** Enable link opening on click */
99
  openOnClick: boolean | 'whenNotEditable';
100
  /** Select link when clicked */
101
  enableClickSelection: boolean;
102
  /** Add links when pasting URLs */
103
  linkOnPaste: boolean;
104
  /** HTML attributes for link elements */
105
  HTMLAttributes: Record<string, any>;
106
  /** XSS protection URI validation function */
107
  isAllowedUri: (url: string, ctx: ValidationContext) => boolean;
108
  /** Determines if URL should be auto-linked */
109
  shouldAutoLink: (url: string) => boolean;
110
  /** @deprecated Use shouldAutoLink */
111
  validate: (url: string) => boolean;
112
}
113

114
interface LinkProtocolOptions {
115
  /** Protocol scheme to register */
116
  scheme: string;
117
  /** Allow optional slashes after protocol */
118
  optionalSlashes?: boolean;
119
}
120
```
121

122
[Link Extension Configuration](./link-configuration.md)
123

124
### Link Commands
125

126
Editor commands for programmatic link manipulation with chainable API integration.
127

128
```typescript { .api }
129
interface LinkCommands {
130
  /** Set a link mark on the current selection */
131
  setLink: (attributes: {
132
    href: string;
133
    target?: string | null;
134
    rel?: string | null;
135
    class?: string | null;
136
  }) => ReturnType;
137
  
138
  /** Toggle a link mark on the current selection */
139
  toggleLink: (attributes?: {
140
    href: string;
141
    target?: string | null;
142
    rel?: string | null;
143
    class?: string | null;
144
  }) => ReturnType;
145
  
146
  /** Remove link mark from current selection */
147
  unsetLink: () => ReturnType;
148
}
149
```
150

151
[Link Commands](./link-commands.md)
152

153
### URL Validation and Security
154

155
XSS protection utilities and URI validation for secure link handling.
156

157
```typescript { .api }
158
function isAllowedUri(
159
  uri: string | undefined,
160
  protocols?: LinkOptions['protocols']
161
): boolean;
162

163
const pasteRegex: RegExp;
164

165
interface ValidationContext {
166
  /** Default validation function */
167
  defaultValidate: (url: string) => boolean;
168
  /** Array of allowed protocols */
169
  protocols: Array<LinkProtocolOptions | string>;
170
  /** Default protocol */
171
  defaultProtocol: string;
172
}
173
```
174

175
[URL Validation](./url-validation.md)
176

177
### Automatic Link Detection
178

179
Smart link detection system with tokenization and validation for creating links as users type.
180

181
```typescript { .api }
182
function autolink(options: AutolinkOptions): Plugin;
183

184
interface AutolinkOptions {
185
  /** Link mark type */
186
  type: MarkType;
187
  /** Default protocol */
188
  defaultProtocol: string;
189
  /** URL validation function */
190
  validate: (url: string) => boolean;
191
  /** Auto-link decision function */
192
  shouldAutoLink: (url: string) => boolean;
193
}
194
```
195

196
[Automatic Link Detection](./autolink.md)
197

198
### Click Handling
199

200
Click event processing for link navigation with configurable behavior and selection options.
201

202
```typescript { .api }
203
function clickHandler(options: ClickHandlerOptions): Plugin;
204

205
interface ClickHandlerOptions {
206
  /** Link mark type */
207
  type: MarkType;
208
  /** Tiptap editor instance */
209
  editor: Editor;
210
  /** Enable click selection */
211
  enableClickSelection?: boolean;
212
}
213
```
214

215
[Click Handling](./click-handling.md)
216

217
### Paste Processing
218

219
Intelligent URL paste handling that automatically converts pasted URLs into clickable links.
220

221
```typescript { .api }
222
function pasteHandler(options: PasteHandlerOptions): Plugin;
223

224
interface PasteHandlerOptions {
225
  /** Tiptap editor instance */
226
  editor: Editor;
227
  /** Default protocol */
228
  defaultProtocol: string;
229
  /** Link mark type */
230
  type: MarkType;
231
}
232
```
233

234
[Paste Processing](./paste-processing.md)
235

236
## Whitespace Utilities
237

238
Unicode whitespace utilities for robust URL processing and validation, sourced from DOMPurify patterns.
239

240
```typescript { .api }
241
/** Unicode whitespace pattern from DOMPurify */
242
export const UNICODE_WHITESPACE_PATTERN: string;
243

244
/** RegExp for matching Unicode whitespace */
245
export const UNICODE_WHITESPACE_REGEX: RegExp;
246

247
/** RegExp for matching whitespace at end of string */
248
export const UNICODE_WHITESPACE_REGEX_END: RegExp;
249

250
/** Global RegExp for replacing Unicode whitespace */
251
export const UNICODE_WHITESPACE_REGEX_GLOBAL: RegExp;
252
```
253

254
## Types
255

256
```typescript { .api }
257
/** @deprecated Use boolean instead */
258
type DeprecatedOpenWhenNotEditable = 'whenNotEditable';
259
```