0
# Link Transforms
1

2
Transform functions provide programmatic control over link creation, modification, and removal within Plate editors. These low-level operations power the plugin's automatic behaviors and can be used directly for custom link handling.
3

4
## Capabilities
5

6
### Link Insertion
7

8
#### insertLink
9

10
Inserts a new link node at the current selection or specified location.
11

12
```typescript { .api }
13
/**
14
 * Insert a link node at the current selection
15
 * @param editor - Slate editor instance
16
 * @param options - Link creation options
17
 * @param insertOptions - Node insertion options
18
 */
19
function insertLink(
20
  editor: SlateEditor, 
21
  options: CreateLinkNodeOptions, 
22
  insertOptions?: InsertNodesOptions
23
): void;
24

25
interface CreateLinkNodeOptions {
26
  /** The URL for the link */
27
  url: string;
28
  /** Child text nodes (optional) */
29
  children?: TText[];
30
  /** Link target attribute (e.g., '_blank') */
31
  target?: string;
32
  /** Text content for the link */
33
  text?: string;
34
}
35
```
36

37
**Usage Examples:**
38

39
```typescript
40
import { insertLink } from "@udecode/plate-link";
41

42
// Insert basic link
43
insertLink(editor, {
44
  url: "https://example.com",
45
  text: "Example"
46
});
47

48
// Insert link with target
49
insertLink(editor, {
50
  url: "https://external.com",
51
  text: "External Link",
52
  target: "_blank"
53
});
54

55
// Insert at specific location
56
insertLink(editor, {
57
  url: "https://example.com",
58
  text: "Link"
59
}, {
60
  at: [0, 1] // Specific path
61
});
62
```
63

64
### Smart Link Operations
65

66
#### upsertLink
67

68
Intelligently inserts or updates links based on current selection context. Handles both creating new links and updating existing ones.
69

70
```typescript { .api }
71
/**
72
 * Insert or update a link based on current selection context
73
 * @param editor - Slate editor instance
74
 * @param options - Comprehensive link options
75
 * @returns Whether the operation was successful
76
 */
77
function upsertLink(
78
  editor: SlateEditor, 
79
  options: UpsertLinkOptions
80
): boolean | undefined;
81

82
interface UpsertLinkOptions extends CreateLinkNodeOptions {
83
  /** Options for node insertion */
84
  insertNodesOptions?: InsertNodesOptions;
85
  /** Whether to insert text inside existing link */
86
  insertTextInLink?: boolean;
87
  /** Skip URL validation step */
88
  skipValidation?: boolean;
89
  /** Options for node unwrapping */
90
  unwrapNodesOptions?: UnwrapNodesOptions;
91
  /** Options for node wrapping */
92
  wrapNodesOptions?: WrapNodesOptions;
93
}
94
```
95

96
**Usage Examples:**
97

98
```typescript
99
import { upsertLink } from "@udecode/plate-link";
100

101
// Smart link insertion/update
102
const success = upsertLink(editor, {
103
  url: "https://example.com",
104
  text: "Example Link"
105
});
106

107
// Update existing link with validation skip
108
upsertLink(editor, {
109
  url: "https://newurl.com",
110
  skipValidation: true,
111
  insertTextInLink: true
112
});
113

114
// Handle selection-based link creation
115
if (editor.selection) {
116
  upsertLink(editor, {
117
    url: "https://example.com"
118
    // Will use selected text if available
119
  });
120
}
121
```
122

123
#### upsertLinkText
124

125
Updates the text content of a link while preserving link formatting and attributes.
126

127
```typescript { .api }
128
/**
129
 * Update the text content of a link element
130
 * @param editor - Slate editor instance
131
 * @param options - Text update options
132
 */
133
function upsertLinkText(
134
  editor: SlateEditor, 
135
  options: UpsertLinkOptions
136
): void;
137
```
138

139
**Usage Examples:**
140

141
```typescript
142
import { upsertLinkText } from "@udecode/plate-link";
143

144
// Update link text content
145
upsertLinkText(editor, {
146
  text: "New Link Text",
147
  url: "https://example.com"
148
});
149
```
150

151
### Link Wrapping
152

153
#### wrapLink
154

155
Wraps the current selection or specified nodes in a link element.
156

157
```typescript { .api }
158
/**
159
 * Wrap selected nodes in a link element
160
 * @param editor - Slate editor instance
161
 * @param options - Wrapping options with URL and target
162
 */
163
function wrapLink(
164
  editor: SlateEditor, 
165
  options: WrapLinkOptions
166
): void;
167

168
interface WrapLinkOptions extends WrapNodesOptions {
169
  /** The URL for the link */
170
  url: string;
171
  /** Optional target attribute */
172
  target?: string;
173
}
174
```
175

176
**Usage Examples:**
177

178
```typescript
179
import { wrapLink } from "@udecode/plate-link";
180

181
// Wrap selection in link
182
wrapLink(editor, {
183
  url: "https://example.com"
184
});
185

186
// Wrap with target attribute
187
wrapLink(editor, {
188
  url: "https://external.com",
189
  target: "_blank"
190
});
191

192
// Wrap specific nodes
193
wrapLink(editor, {
194
  url: "https://example.com",
195
  at: editor.selection
196
});
197
```
198

199
### Link Removal
200

201
#### unwrapLink
202

203
Removes link formatting from nodes while preserving text content.
204

205
```typescript { .api }
206
/**
207
 * Remove link formatting from nodes
208
 * @param editor - Slate editor instance
209
 * @param options - Unwrapping options
210
 * @returns Whether any links were unwrapped
211
 */
212
function unwrapLink(
213
  editor: SlateEditor, 
214
  options?: { split?: boolean } & UnwrapNodesOptions
215
): boolean;
216
```
217

218
**Usage Examples:**
219

220
```typescript
221
import { unwrapLink } from "@udecode/plate-link";
222

223
// Remove link from selection
224
const removed = unwrapLink(editor);
225

226
// Remove with splitting behavior
227
unwrapLink(editor, { split: true });
228

229
// Remove from specific location
230
unwrapLink(editor, {
231
  at: [0, 1, 0]
232
});
233
```
234

235
### React-Specific Transforms
236

237
#### submitFloatingLink
238

239
Processes floating link form submission, validates the URL, and inserts or updates the link.
240

241
```typescript { .api }
242
/**
243
 * Process floating link form submission
244
 * @param editor - Slate editor instance
245
 * @returns Whether the submission was successful
246
 */
247
function submitFloatingLink(
248
  editor: SlateEditor
249
): boolean | undefined;
250
```
251

252
**Usage Examples:**
253

254
```typescript
255
import { submitFloatingLink } from "@udecode/plate-link/react";
256

257
// Handle form submission
258
const handleSubmit = () => {
259
  const success = submitFloatingLink(editor);
260
  if (success) {
261
    console.log("Link submitted successfully");
262
  }
263
};
264
```
265

266
### Advanced Transform Patterns
267

268
#### Conditional Link Operations
269

270
```typescript
271
import { upsertLink, unwrapLink } from "@udecode/plate-link";
272

273
// Toggle link behavior
274
function toggleLink(editor: SlateEditor, url: string) {
275
  const hasLink = editor.api.some({
276
    match: { type: 'a' }
277
  });
278
  
279
  if (hasLink) {
280
    unwrapLink(editor);
281
  } else {
282
    upsertLink(editor, { url });
283
  }
284
}
285
```
286

287
#### Batch Link Operations
288

289
```typescript
290
import { insertLink } from "@udecode/plate-link";
291

292
// Insert multiple links
293
function insertMultipleLinks(editor: SlateEditor, links: Array<{url: string, text: string}>) {
294
  editor.tf.withoutNormalizing(() => {
295
    links.forEach((link, index) => {
296
      insertLink(editor, link, {
297
        at: [index]
298
      });
299
    });
300
  });
301
}
302
```
303

304
#### Link Validation and Transformation
305

306
```typescript
307
import { upsertLink, validateUrl } from "@udecode/plate-link";
308

309
// Insert with validation
310
function insertValidatedLink(editor: SlateEditor, url: string, text: string) {
311
  if (validateUrl(editor, url)) {
312
    return upsertLink(editor, { url, text });
313
  }
314
  throw new Error('Invalid URL');
315
}
316
```