0
# Core Link Plugin
1

2
The BaseLinkPlugin provides foundational hyperlink functionality for Plate editors, including automatic link detection, HTML serialization, and configurable URL validation.
3

4
## Capabilities
5

6
### BaseLinkPlugin
7

8
Core plugin that enables hyperlink support with automatic wrapping, paste handling, and HTML serialization.
9

10
```typescript { .api }
11
/**
12
 * Core link plugin with editor overrides, HTML parsing, and normalization
13
 */
14
const BaseLinkPlugin: PlatePlugin<BaseLinkConfig>;
15

16
type BaseLinkConfig = PluginConfig<'a', {
17
  /** List of allowed URL schemes @default ['http', 'https', 'mailto', 'tel'] */
18
  allowedSchemes?: string[];
19
  /** Skips sanitation of links @default false */
20
  dangerouslySkipSanitization?: boolean;
21
  /** Default HTML attributes for link elements */
22
  defaultLinkAttributes?: React.AnchorHTMLAttributes<HTMLAnchorElement>;
23
  /** Forces form submission behavior */
24
  forceSubmit?: boolean;
25
  /** Keeps selected text on pasting links @default true */
26
  keepSelectedTextOnPaste?: boolean;
27
  /** Custom config for rangeBeforeOptions */
28
  rangeBeforeOptions?: EditorBeforeOptions;
29
  /** Hotkeys to trigger floating link @default 'meta+k, ctrl+k' */
30
  triggerFloatingLinkHotkeys?: string[] | string;
31
  /** Promise-based URL getter for keyboard shortcuts */
32
  getLinkUrl?: (prevUrl: string | null) => Promise<string | null>;
33
  /** Callback to get href for a URL */
34
  getUrlHref?: (url: string) => string | undefined;
35
  /** URL validation function @default isUrl */
36
  isUrl?: (text: string) => boolean;
37
  /** Transform URL input before validation */
38
  transformInput?: (url: string) => string | undefined;
39
}>;
40
```
41

42
**Usage Examples:**
43

44
```typescript
45
import { createPlateEditor } from "@udecode/plate";
46
import { BaseLinkPlugin } from "@udecode/plate-link";
47

48
// Basic setup
49
const editor = createPlateEditor({
50
  plugins: [BaseLinkPlugin]
51
});
52

53
// Custom configuration
54
const customEditor = createPlateEditor({
55
  plugins: [
56
    BaseLinkPlugin.configure({
57
      options: {
58
        allowedSchemes: ['http', 'https', 'ftp'],
59
        defaultLinkAttributes: { target: '_blank', rel: 'noopener' },
60
        transformInput: (url) => {
61
          // Auto-add https:// to bare domains
62
          if (!url.includes('://') && !url.startsWith('/')) {
63
            return `https://${url}`;
64
          }
65
          return url;
66
        }
67
      }
68
    })
69
  ]
70
});
71
```
72

73
### withLink Editor Enhancement
74

75
Editor enhancement function that adds automatic link wrapping behavior, paste handling, and normalization.
76

77
```typescript { .api }
78
/**
79
 * Editor enhancement adding automatic link detection and paste handling
80
 * @param editor - The Slate editor instance
81
 * @param getOptions - Function to get current plugin options
82
 * @param tf - Transform functions
83
 * @param type - Node type for links
84
 */
85
const withLink: OverrideEditor<BaseLinkConfig>;
86
```
87

88
**Key Features:**
89

90
- **Auto-wrapping**: Automatically wraps URLs in link elements when typing space or pressing enter
91
- **Paste handling**: Intelligently handles pasted URLs, preserving or replacing selected text
92
- **Normalization**: Ensures proper cursor positioning and text node structure around links
93

94
**Usage Examples:**
95

96
```typescript
97
import { createSlateEditor } from '@udecode/plate';
98
import { withLink } from '@udecode/plate-link';
99

100
// Applied automatically by BaseLinkPlugin
101
const editor = createSlateEditor().overrideEditor(withLink);
102
```
103

104
### Plugin Configuration Options
105

106
#### URL Scheme Validation
107

108
Control which URL schemes are considered valid links.
109

110
```typescript
111
BaseLinkPlugin.configure({
112
  options: {
113
    allowedSchemes: ['http', 'https', 'mailto', 'tel', 'ftp']
114
  }
115
});
116
```
117

118
#### Custom URL Processing
119

120
Transform and validate URLs with custom logic.
121

122
```typescript
123
BaseLinkPlugin.configure({
124
  options: {
125
    // Transform input before validation
126
    transformInput: (url) => {
127
      if (!url.includes('://')) {
128
        return `https://${url}`;
129
      }
130
      return url;
131
    },
132
    
133
    // Custom URL validation
134
    isUrl: (text) => {
135
      return /^https?:\/\//.test(text) || text.includes('@');
136
    },
137
    
138
    // Get different href from display text
139
    getUrlHref: (url) => {
140
      if (url.startsWith('www.')) {
141
        return `https://${url}`;
142
      }
143
      return url;
144
    }
145
  }
146
});
147
```
148

149
#### Paste Behavior Configuration
150

151
Control how pasted URLs interact with selected text.
152

153
```typescript
154
BaseLinkPlugin.configure({
155
  options: {
156
    // Keep selected text when pasting URLs
157
    keepSelectedTextOnPaste: true,
158
    
159
    // Custom range detection for auto-wrapping
160
    rangeBeforeOptions: {
161
      matchString: ' ',
162
      skipInvalid: true,
163
      afterMatch: true,
164
      matchBlockStart: true
165
    }
166
  }
167
});
168
```