0
# Base Media Plugins
1

2
Core Slate plugins that provide the foundation for all media handling in Plate. Each plugin defines element types, configurations, and basic transforms for different media types.
3

4
## Capabilities
5

6
### Base Image Plugin
7

8
Complete image plugin with upload, embed, and HTML parsing capabilities.
9

10
```typescript { .api }
11
/**
12
 * Complete image plugin with upload, embed, and HTML parsing capabilities
13
 * Handles automatic image detection from URLs and file uploads
14
 */
15
const BaseImagePlugin: TSlatePlugin<ImageConfig>;
16

17
interface ImageConfig extends MediaPluginOptions {
18
  disableEmbedInsert?: boolean;
19
  disableUploadInsert?: boolean;
20
  uploadImage?: (dataUrl: ArrayBuffer | string) => Promise<string> | string;
21
}
22
```
23

24
**Usage Example:**
25

26
```typescript
27
import { BaseImagePlugin } from "@udecode/plate-media";
28
import { createSlateEditor } from "@udecode/plate";
29

30
const editor = createSlateEditor({
31
  plugins: [
32
    BaseImagePlugin.configure({
33
      options: {
34
        disableEmbedInsert: false,
35
        disableUploadInsert: false,
36
        uploadImage: async (file) => {
37
          // Your upload logic
38
          const formData = new FormData();
39
          formData.append('file', file);
40
          const response = await fetch('/upload', {
41
            method: 'POST',
42
            body: formData
43
          });
44
          const data = await response.json();
45
          return data.url;
46
        }
47
      }
48
    })
49
  ]
50
});
51
```
52

53
### Base Video Plugin
54

55
Base plugin for video elements with width and height attribute support.
56

57
```typescript { .api }
58
/**
59
 * Base plugin for video elements with void node configuration
60
 * Supports width and height attributes for responsive sizing
61
 */
62
const BaseVideoPlugin: TSlatePlugin<VideoConfig>;
63

64
interface VideoConfig extends MediaPluginOptions {
65
  // Inherits standard media plugin options
66
}
67
```
68

69
The plugin configuration includes:
70
- `key: KEYS.video` - Element type identifier
71
- `node: { dangerouslyAllowAttributes: ['width', 'height'], isElement: true, isVoid: true }` - Node behavior
72
- Support for width and height HTML attributes for responsive video sizing
73

74
### Base Audio Plugin
75

76
Base plugin for audio elements with void node configuration.
77

78
```typescript { .api }
79
/**
80
 * Base plugin for audio elements with void node configuration
81
 * Handles audio file embedding and playback controls
82
 */
83
const BaseAudioPlugin: TSlatePlugin<AudioConfig>;
84

85
interface AudioConfig extends MediaPluginOptions {
86
  // Inherits standard media plugin options
87
}
88
```
89

90
The plugin configuration includes:
91
- `key: KEYS.audio` - Element type identifier  
92
- `node: { isElement: true, isVoid: true }` - Void element behavior
93
- Integration with HTML audio element for playback
94

95
### Base File Plugin
96

97
Base plugin for generic file elements with void node configuration.
98

99
```typescript { .api }
100
/**
101
 * Base plugin for generic file elements with void node configuration
102
 * Handles file attachments and download functionality
103
 */
104
const BaseFilePlugin: TSlatePlugin<FileConfig>;
105

106
interface FileConfig extends MediaPluginOptions {
107
  // Inherits standard media plugin options
108
}
109
```
110

111
The plugin configuration includes:
112
- `key: KEYS.file` - Element type identifier
113
- `node: { isElement: true, isVoid: true }` - Void element behavior
114
- Support for any file type attachment and download links
115

116
### Editor Overrides
117

118
Advanced functionality that extends editor behavior for automatic media handling.
119

120
#### Image Embed Override
121

122
```typescript { .api }
123
/**
124
 * Automatically inserts images when pasting image URLs
125
 * Detects image URLs in clipboard content and converts to image elements
126
 */
127
function withImageEmbed(config: ImageConfig): EditorOverride<ImageConfig>;
128
```
129

130
**Usage Example:**
131

132
```typescript
133
import { withImageEmbed } from "@udecode/plate-media";
134

135
const editor = createSlateEditor({
136
  plugins: [
137
    BaseImagePlugin.configure({
138
      overrides: {
139
        insert: withImageEmbed
140
      }
141
    })
142
  ]
143
});
144

145
// Now pasting "https://example.com/image.jpg" will automatically create an image element
146
```
147

148
#### Image Upload Override
149

150
```typescript { .api }
151
/**
152
 * Handles image uploads from clipboard and file drops
153
 * Processes files from drag & drop or paste operations
154
 */
155
function withImageUpload(config: ImageConfig): EditorOverride<ImageConfig>;
156
```
157

158
**Usage Example:**
159

160
```typescript
161
import { withImageUpload } from "@udecode/plate-media";
162

163
const editor = createSlateEditor({
164
  plugins: [
165
    BaseImagePlugin.configure({
166
      overrides: {
167
        insert: withImageUpload,
168
        drop: withImageUpload
169
      },
170
      options: {
171
        uploadImage: async (file) => {
172
          // Handle the file upload
173
          return uploadToServer(file);
174
        }
175
      }
176
    })
177
  ]
178
});
179

180
// Now drag & drop or paste of image files will trigger upload
181
```
182

183
## Configuration Options
184

185
### Media Plugin Options
186

187
Base configuration interface shared across all media plugins.
188

189
```typescript { .api }
190
interface MediaPluginOptions {
191
  /** Custom URL validation function */
192
  isUrl?: (text: string) => boolean;
193
  /** URL transformation function for processing URLs before embedding */
194
  transformUrl?: (url: string) => string;
195
}
196
```
197

198
**Usage Example:**
199

200
```typescript
201
const mediaOptions: MediaPluginOptions = {
202
  isUrl: (text) => {
203
    // Custom URL validation logic
204
    return /^https?:\/\/.+/.test(text);
205
  },
206
  transformUrl: (url) => {
207
    // Transform URLs (e.g., add query parameters)
208
    return url + '?editor=plate';
209
  }
210
};
211
```
212

213
## Element Keys
214

215
Constants used to identify different media element types in the Slate editor.
216

217
```typescript { .api }
218
enum KEYS {
219
  image = 'img',
220
  video = 'video', 
221
  audio = 'audio',
222
  file = 'file',
223
  mediaEmbed = 'media_embed',
224
  placeholder = 'placeholder'
225
}
226
```
227

228
These keys are used internally by the plugins to:
229
- Register element types with Slate
230
- Identify elements during transforms
231
- Apply type-specific rendering and behavior