0
# Link Extension Configuration
1

2
Comprehensive configuration options for the Link extension, including behavior settings, validation functions, and HTML attribute customization.
3

4
## Capabilities
5

6
### Link Extension Class
7

8
Main Link extension class providing mark-based link functionality for Tiptap editors.
9

10
```typescript { .api }
11
/**
12
 * Creates a Link mark extension for Tiptap editor
13
 * @returns Configured Link mark extension
14
 */
15
const Link: Mark<LinkOptions>;
16
```
17

18
**Usage Examples:**
19

20
```typescript
21
import { Editor } from "@tiptap/core";
22
import { Link } from "@tiptap/extension-link";
23

24
// Basic configuration
25
const editor = new Editor({
26
  extensions: [
27
    Link.configure({
28
      openOnClick: true,
29
      autolink: true,
30
    }),
31
  ],
32
});
33

34
// Advanced configuration with custom protocols
35
const editor = new Editor({
36
  extensions: [
37
    Link.configure({
38
      openOnClick: true,
39
      autolink: true,
40
      linkOnPaste: true,
41
      protocols: ['ftp', 'git', { scheme: 'custom', optionalSlashes: true }],
42
      defaultProtocol: 'https',
43
      HTMLAttributes: {
44
        target: '_blank',
45
        rel: 'noopener noreferrer nofollow',
46
        class: 'custom-link',
47
      },
48
      isAllowedUri: (url, { defaultValidate, protocols, defaultProtocol }) => {
49
        // Custom validation logic
50
        if (url.startsWith('./') || url.startsWith('../')) {
51
          return true; // Allow relative URLs
52
        }
53
        return defaultValidate(url);
54
      },
55
      shouldAutoLink: (url) => {
56
        // Don't auto-link localhost URLs
57
        return !url.includes('localhost');
58
      },
59
    }),
60
  ],
61
});
62
```
63

64
### Link Options Interface
65

66
Comprehensive configuration interface for Link extension behavior and validation.
67

68
```typescript { .api }
69
interface LinkOptions {
70
  /**
71
   * If enabled, the extension will automatically add links as you type.
72
   * @default true
73
   */
74
  autolink: boolean;
75

76
  /**
77
   * An array of custom protocols to be registered with linkifyjs.
78
   * @default []
79
   */
80
  protocols: Array<LinkProtocolOptions | string>;
81

82
  /**
83
   * Default protocol to use when no protocol is specified.
84
   * @default 'http'
85
   */
86
  defaultProtocol: string;
87

88
  /**
89
   * If enabled, links will be opened on click.
90
   * @default true
91
   */
92
  openOnClick: boolean | DeprecatedOpenWhenNotEditable;
93

94
  /**
95
   * If enabled, the link will be selected when clicked.
96
   * @default false
97
   */
98
  enableClickSelection: boolean;
99

100
  /**
101
   * Adds a link to the current selection if the pasted content only contains an url.
102
   * @default true
103
   */
104
  linkOnPaste: boolean;
105

106
  /**
107
   * HTML attributes to add to the link element.
108
   * @default { target: '_blank', rel: 'noopener noreferrer nofollow', class: null }
109
   */
110
  HTMLAttributes: Record<string, any>;
111

112
  /**
113
   * A validation function which is used for configuring link verification for preventing XSS attacks.
114
   * Only modify this if you know what you're doing.
115
   * @param url - The URL to be validated
116
   * @param ctx - Validation context with default validation function and protocol info
117
   * @returns True if the URL is valid, false otherwise
118
   */
119
  isAllowedUri: (
120
    url: string,
121
    ctx: {
122
      defaultValidate: (url: string) => boolean;
123
      protocols: Array<LinkProtocolOptions | string>;
124
      defaultProtocol: string;
125
    }
126
  ) => boolean;
127

128
  /**
129
   * Determines whether a valid link should be automatically linked in the content.
130
   * @param url - The URL that has already been validated
131
   * @returns True if the link should be auto-linked; false if it should not be auto-linked
132
   */
133
  shouldAutoLink: (url: string) => boolean;
134

135
  /**
136
   * @deprecated Use the shouldAutoLink option instead.
137
   * A validation function that modifies link verification for the auto linker.
138
   * @param url - The url to be validated
139
   * @returns True if the url is valid, false otherwise
140
   */
141
  validate: (url: string) => boolean;
142
}
143
```
144

145
### Link Protocol Options
146

147
Configuration for custom protocol registration with linkifyjs.
148

149
```typescript { .api }
150
interface LinkProtocolOptions {
151
  /**
152
   * The protocol scheme to be registered.
153
   * @example 'ftp'
154
   * @example 'git'
155
   */
156
  scheme: string;
157

158
  /**
159
   * If enabled, it allows optional slashes after the protocol.
160
   * @default false
161
   */
162
  optionalSlashes?: boolean;
163
}
164
```
165

166
**Usage Examples:**
167

168
```typescript
169
// String protocols
170
const protocols = ['ftp', 'ssh', 'git'];
171

172
// Object protocols with options
173
const protocols = [
174
  'ftp',
175
  { scheme: 'git', optionalSlashes: true },
176
  { scheme: 'custom', optionalSlashes: false },
177
];
178

179
const editor = new Editor({
180
  extensions: [
181
    Link.configure({
182
      protocols,
183
      defaultProtocol: 'https',
184
    }),
185
  ],
186
});
187
```
188

189
### Default Configuration
190

191
The Link extension provides sensible defaults for all configuration options.
192

193
```typescript { .api }
194
/**
195
 * Default Link extension configuration
196
 */
197
const defaultOptions: LinkOptions = {
198
  openOnClick: true,
199
  enableClickSelection: false,
200
  linkOnPaste: true,
201
  autolink: true,
202
  protocols: [],
203
  defaultProtocol: 'http',
204
  HTMLAttributes: {
205
    target: '_blank',
206
    rel: 'noopener noreferrer nofollow',
207
    class: null,
208
  },
209
  isAllowedUri: (url, ctx) => !!isAllowedUri(url, ctx.protocols),
210
  validate: url => !!url,
211
  shouldAutoLink: url => !!url,
212
};
213
```
214

215
### Link Attributes
216

217
HTML attributes that can be configured for link elements.
218

219
```typescript { .api }
220
interface LinkAttributes {
221
  /** Link URL */
222
  href: string | null;
223
  /** Link target (_blank, _self, etc.) */
224
  target: string | null;
225
  /** Link relationship (noopener, noreferrer, etc.) */
226
  rel: string | null;
227
  /** CSS class name */
228
  class: string | null;
229
}
230
```
231

232
**Usage Examples:**
233

234
```typescript
235
// Configure HTML attributes
236
const editor = new Editor({
237
  extensions: [
238
    Link.configure({
239
      HTMLAttributes: {
240
        target: '_blank',
241
        rel: 'noopener noreferrer nofollow',
242
        class: 'custom-link-class',
243
        'data-track': 'link-click',
244
      },
245
    }),
246
  ],
247
});
248
```
249

250
## Types
251

252
```typescript { .api }
253
/** @deprecated The default behavior is now to open links when the editor is not editable */
254
type DeprecatedOpenWhenNotEditable = 'whenNotEditable';
255
```