0
# Plate Link Plugin
1

2
The Plate Link Plugin provides comprehensive hyperlink functionality for the Plate rich text editor framework. It enables users to insert, edit, and manage hyperlinks within rich text content with advanced features including URL validation, automatic link detection, keyboard shortcuts, and floating UI components.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import { BaseLinkPlugin } from "@udecode/plate-link";
15
import { LinkPlugin } from "@udecode/plate-link/react";
16
```
17

18
For individual utilities and transforms:
19

20
```typescript
21
import { 
22
  upsertLink, 
23
  validateUrl, 
24
  encodeUrlIfNeeded 
25
} from "@udecode/plate-link";
26
```
27

28
For React components and hooks:
29

30
```typescript
31
import { 
32
  useLink, 
33
  useLinkToolbarButton, 
34
  FloatingLinkUrlInput 
35
} from "@udecode/plate-link/react";
36
```
37

38
## Basic Usage
39

40
```typescript
41
import { createPlateEditor } from "@udecode/plate";
42
import { BaseLinkPlugin } from "@udecode/plate-link";
43

44
// Basic plugin setup
45
const editor = createPlateEditor({
46
  plugins: [
47
    BaseLinkPlugin.configure({
48
      options: {
49
        allowedSchemes: ['http', 'https', 'mailto', 'tel'],
50
        keepSelectedTextOnPaste: true,
51
        triggerFloatingLinkHotkeys: 'meta+k, ctrl+k'
52
      }
53
    })
54
  ]
55
});
56

57
// Insert a link programmatically
58
import { insertLink } from "@udecode/plate-link";
59

60
insertLink(editor, { 
61
  url: "https://example.com", 
62
  text: "Example Link" 
63
});
64
```
65

66
## Architecture
67

68
The Plate Link Plugin is built around several key components:
69

70
- **Base Plugin**: Core link functionality with editor transforms and validation
71
- **React Plugin**: Enhanced plugin with floating UI, keyboard shortcuts, and React-specific features
72
- **Transform Functions**: Low-level operations for link insertion, modification, and removal
73
- **Utility Functions**: URL processing, validation, and attribute generation
74
- **React Components**: Pre-built UI components and hooks for link editing interfaces
75
- **Floating UI System**: Modal-style link editing with positioning and keyboard handling
76

77
## Capabilities
78

79
### Core Link Plugin
80

81
Foundation plugin providing basic link functionality, HTML serialization, and editor integration.
82

83
```typescript { .api }
84
const BaseLinkPlugin: PlatePlugin<BaseLinkConfig>;
85

86
type BaseLinkConfig = PluginConfig<'a', {
87
  allowedSchemes?: string[];
88
  dangerouslySkipSanitization?: boolean;
89
  defaultLinkAttributes?: React.AnchorHTMLAttributes<HTMLAnchorElement>;
90
  forceSubmit?: boolean;
91
  keepSelectedTextOnPaste?: boolean;
92
  rangeBeforeOptions?: EditorBeforeOptions;
93
  triggerFloatingLinkHotkeys?: string[] | string;
94
  getLinkUrl?: (prevUrl: string | null) => Promise<string | null>;
95
  getUrlHref?: (url: string) => string | undefined;
96
  isUrl?: (text: string) => boolean;
97
  transformInput?: (url: string) => string | undefined;
98
}>;
99
```
100

101
[Core Plugin](./core-plugin.md)
102

103
### React Integration
104

105
React-enhanced plugin with floating UI, state management, and component integration.
106

107
```typescript { .api }
108
const LinkPlugin: PlatePlugin<LinkConfig>;
109

110
type LinkConfig = ExtendConfig<BaseLinkConfig, {
111
  isEditing: boolean;
112
  mode: FloatingLinkMode;
113
  mouseDown: boolean;
114
  newTab: boolean;
115
  openEditorId: string | null;
116
  text: string;
117
  updated: boolean;
118
  url: string;
119
  triggerFloatingLinkHotkeys?: string;
120
}>;
121

122
type FloatingLinkMode = '' | 'edit' | 'insert';
123
```
124

125
[React Integration](./react-integration.md)
126

127
### Link Transforms
128

129
Programmatic functions for creating, modifying, and removing links within the editor.
130

131
```typescript { .api }
132
function insertLink(
133
  editor: SlateEditor, 
134
  options: CreateLinkNodeOptions, 
135
  insertOptions?: InsertNodesOptions
136
): void;
137

138
function upsertLink(
139
  editor: SlateEditor, 
140
  options: UpsertLinkOptions
141
): boolean | undefined;
142

143
function unwrapLink(
144
  editor: SlateEditor, 
145
  options?: { split?: boolean } & UnwrapNodesOptions
146
): boolean;
147
```
148

149
[Link Transforms](./transforms.md)
150

151
### URL Utilities
152

153
Utility functions for URL processing, validation, and encoding/decoding.
154

155
```typescript { .api }
156
function validateUrl(editor: SlateEditor, url: string): boolean;
157
function encodeUrlIfNeeded(url: string): string;
158
function safeDecodeUrl(url: string): string;
159
function getLinkAttributes(
160
  editor: SlateEditor, 
161
  link: TLinkElement
162
): React.AnchorHTMLAttributes<HTMLAnchorElement>;
163
```
164

165
[URL Utilities](./url-utils.md)
166

167
### React Components
168

169
Pre-built React components and hooks for building link editing interfaces.
170

171
```typescript { .api }
172
function useLink({ element }: { element: TLinkElement }): {
173
  props: React.AnchorHTMLAttributes<HTMLAnchorElement>;
174
};
175

176
function useLinkToolbarButton(): {
177
  props: {
178
    pressed: boolean;
179
    onClick: () => void;
180
    onMouseDown: (e: React.MouseEvent) => void;
181
  };
182
};
183

184
const FloatingLinkUrlInput: React.FC;
185
const FloatingLinkNewTabInput: React.FC;
186
```
187

188
[React Components](./react-components.md)
189

190
### Floating Link Interface
191

192
Complete floating UI system for inserting and editing links with keyboard shortcuts and positioning.
193

194
```typescript { .api }
195
function triggerFloatingLink(
196
  editor: SlateEditor, 
197
  options?: { focused?: boolean }
198
): void;
199

200
function useFloatingLinkInsert(state: LinkFloatingToolbarState): {
201
  hidden: boolean;
202
  props: object;
203
  ref: RefObject;
204
  textInputProps: object;
205
};
206

207
function useFloatingLinkEdit(state: LinkFloatingToolbarState): {
208
  editButtonProps: object;
209
  props: object;
210
  ref: RefObject;
211
  unlinkButtonProps: object;
212
};
213
```
214

215
[Floating Interface](./floating-interface.md)
216

217
## Types
218

219
```typescript { .api }
220
// Core types (imported from @udecode/plate)
221
type TLinkElement = {
222
  type: 'a';
223
  url: string;
224
  target?: string;
225
  children: TText[];
226
}
227

228
interface CreateLinkNodeOptions {
229
  url: string;
230
  children?: TText[];
231
  target?: string;
232
  text?: string;
233
}
234

235
interface UpsertLinkOptions extends CreateLinkNodeOptions {
236
  insertNodesOptions?: InsertNodesOptions;
237
  insertTextInLink?: boolean;
238
  skipValidation?: boolean;
239
  unwrapNodesOptions?: UnwrapNodesOptions;
240
  wrapNodesOptions?: WrapNodesOptions;
241
}
242

243
interface LinkFloatingToolbarState {
244
  floatingOptions?: UseVirtualFloatingOptions;
245
}
246
```