0
# Link Commands
1

2
Editor commands for programmatic link manipulation with chainable API integration. These commands extend the Tiptap Commands interface to provide link-specific functionality.
3

4
## Capabilities
5

6
### Set Link Command
7

8
Sets a link mark on the current selection with specified attributes.
9

10
```typescript { .api }
11
/**
12
 * Set a link mark on the current selection
13
 * @param attributes - Link attributes including href and optional target, rel, class
14
 * @returns Chainable command result
15
 */
16
setLink: (attributes: {
17
  href: string;
18
  target?: string | null;
19
  rel?: string | null;
20
  class?: string | null;
21
}) => ReturnType;
22
```
23

24
**Usage Examples:**
25

26
```typescript
27
import { Editor } from "@tiptap/core";
28
import { Link } from "@tiptap/extension-link";
29

30
const editor = new Editor({
31
  extensions: [Link],
32
});
33

34
// Basic link setting
35
editor.commands.setLink({ href: 'https://tiptap.dev' });
36

37
// Link with custom attributes
38
editor.commands.setLink({
39
  href: 'https://example.com',
40
  target: '_blank',
41
  rel: 'noopener noreferrer',
42
  class: 'external-link',
43
});
44

45
// Chainable with other commands
46
editor
47
  .chain()
48
  .focus()
49
  .selectAll()
50
  .setLink({ href: 'https://tiptap.dev' })
51
  .run();
52
```
53

54
### Toggle Link Command
55

56
Toggles a link mark on the current selection. If a link exists, it removes it; if no link exists, it creates one with the provided attributes.
57

58
```typescript { .api }
59
/**
60
 * Toggle a link mark on the current selection
61
 * @param attributes - Optional link attributes. If not provided and link exists, removes the link
62
 * @returns Chainable command result
63
 */
64
toggleLink: (attributes?: {
65
  href: string;
66
  target?: string | null;
67
  rel?: string | null;
68
  class?: string | null;
69
}) => ReturnType;
70
```
71

72
**Usage Examples:**
73

74
```typescript
75
// Toggle link with URL
76
editor.commands.toggleLink({ href: 'https://tiptap.dev' });
77

78
// Toggle with custom attributes
79
editor.commands.toggleLink({
80
  href: 'https://example.com',
81
  target: '_blank',
82
  class: 'toggled-link',
83
});
84

85
// Toggle without attributes (removes existing link)
86
editor.commands.toggleLink();
87

88
// Chainable toggle
89
editor
90
  .chain()
91
  .focus()
92
  .toggleLink({ href: 'https://tiptap.dev' })
93
  .run();
94
```
95

96
### Unset Link Command
97

98
Removes the link mark from the current selection, converting linked text back to plain text.
99

100
```typescript { .api }
101
/**
102
 * Remove link mark from current selection
103
 * @returns Chainable command result
104
 */
105
unsetLink: () => ReturnType;
106
```
107

108
**Usage Examples:**
109

110
```typescript
111
// Remove link from selection
112
editor.commands.unsetLink();
113

114
// Chainable unset
115
editor
116
  .chain()
117
  .focus()
118
  .selectAll()
119
  .unsetLink()
120
  .run();
121

122
// Conditional link removal
123
if (editor.isActive('link')) {
124
  editor.commands.unsetLink();
125
}
126
```
127

128
### Commands Interface Extension
129

130
The Link extension extends the Tiptap Commands interface with link-specific methods.
131

132
```typescript { .api }
133
declare module '@tiptap/core' {
134
  interface Commands<ReturnType> {
135
    link: {
136
      /**
137
       * Set a link mark
138
       * @param attributes The link attributes
139
       */
140
      setLink: (attributes: {
141
        href: string;
142
        target?: string | null;
143
        rel?: string | null;
144
        class?: string | null;
145
      }) => ReturnType;
146

147
      /**
148
       * Toggle a link mark
149
       * @param attributes The link attributes
150
       */
151
      toggleLink: (attributes?: {
152
        href: string;
153
        target?: string | null;
154
        rel?: string | null;
155
        class?: string | null;
156
      }) => ReturnType;
157

158
      /**
159
       * Unset a link mark
160
       */
161
      unsetLink: () => ReturnType;
162
    };
163
  }
164
}
165
```
166

167
### Command Validation
168

169
All link commands include built-in URL validation to prevent XSS attacks and ensure only allowed URIs are processed.
170

171
**Validation Behavior:**
172

173
```typescript
174
// Commands automatically validate URLs using the configured isAllowedUri function
175
editor.commands.setLink({ href: 'javascript:alert("xss")' }); // Returns false, link not set
176

177
editor.commands.setLink({ href: 'https://safe-url.com' }); // Returns true, link set
178

179
// Custom validation context is used
180
const isValid = editor.extensionManager.extensions
181
  .find(ext => ext.name === 'link')
182
  .options.isAllowedUri('https://example.com', {
183
    defaultValidate: (url) => /* default validation */,
184
    protocols: ['http', 'https', 'ftp'],
185
    defaultProtocol: 'https'
186
  });
187
```
188

189
### Command Chaining
190

191
All link commands support Tiptap's chainable command API for complex operations.
192

193
**Usage Examples:**
194

195
```typescript
196
// Complex command chain
197
editor
198
  .chain()
199
  .focus()
200
  .selectAll()
201
  .unsetLink() // Remove any existing links
202
  .setTextSelection({ from: 10, to: 20 })
203
  .setLink({ href: 'https://tiptap.dev' })
204
  .setTextSelection({ from: 30, to: 40 })
205
  .toggleLink({ href: 'https://example.com' })
206
  .run();
207

208
// Conditional chaining
209
const chain = editor.chain().focus();
210

211
if (shouldAddLink) {
212
  chain.setLink({ href: 'https://tiptap.dev' });
213
} else {
214
  chain.unsetLink();
215
}
216

217
chain.run();
218
```
219

220
### Command State Checking
221

222
Use Tiptap's state checking methods to determine link status before executing commands.
223

224
**Usage Examples:**
225

226
```typescript
227
// Check if selection has a link
228
const hasLink = editor.isActive('link');
229

230
// Get current link attributes
231
const linkAttrs = editor.getAttributes('link');
232
console.log(linkAttrs.href); // Current link URL
233

234
// Conditional command execution
235
if (editor.isActive('link')) {
236
  editor.commands.unsetLink();
237
} else {
238
  editor.commands.setLink({ href: 'https://tiptap.dev' });
239
}
240
```
241

242
## Types
243

244
```typescript { .api }
245
/** Link command attribute interface */
246
interface LinkCommandAttributes {
247
  /** Link URL (required) */
248
  href: string;
249
  /** Link target attribute */
250
  target?: string | null;
251
  /** Link relationship attribute */
252
  rel?: string | null;
253
  /** CSS class attribute */
254
  class?: string | null;
255
}
256
```