0
# Plate Media
1

2
Plate Media provides comprehensive media handling capabilities for the Plate rich text editor framework, enabling developers to embed and manage various types of media content including images, videos (YouTube, Vimeo), audio files, generic files, and embeddable content like tweets. The plugin offers a modular architecture with support for placeholder handling during media loading, media embedding with URL parsing, resizable media components, and caption functionality.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import { 
15
  BaseImagePlugin, 
16
  BaseVideoPlugin, 
17
  BaseAudioPlugin, 
18
  BaseFilePlugin,
19
  BaseMediaEmbedPlugin,
20
  BasePlaceholderPlugin,
21
  insertImage,
22
  insertImageFromFiles,
23
  insertMediaEmbed,
24
  isImageUrl,
25
  parseVideoUrl,
26
  parseTwitterUrl
27
} from "@udecode/plate-media";
28
```
29

30
React components and hooks:
31

32
```typescript
33
import { 
34
  ImagePlugin, 
35
  VideoPlugin, 
36
  AudioPlugin, 
37
  FilePlugin,
38
  MediaEmbedPlugin,
39
  PlaceholderPlugin,
40
  openImagePreview,
41
  useImagePreview,
42
  useMediaState
43
} from "@udecode/plate-media/react";
44
```
45

46
For CommonJS:
47

48
```javascript
49
const { 
50
  BaseImagePlugin, 
51
  BaseVideoPlugin, 
52
  BaseAudioPlugin, 
53
  BaseFilePlugin 
54
} = require("@udecode/plate-media");
55
```
56

57
## Basic Usage
58

59
```typescript
60
import { 
61
  BaseImagePlugin, 
62
  BaseMediaEmbedPlugin,
63
  insertImage,
64
  insertMediaEmbed 
65
} from "@udecode/plate-media";
66
import { createSlateEditor } from "@udecode/plate";
67

68
// Create editor with media plugins
69
const editor = createSlateEditor({
70
  plugins: [
71
    BaseImagePlugin.configure({
72
      options: {
73
        uploadImage: async (file) => {
74
          // Upload logic here
75
          return "https://example.com/uploaded-image.jpg";
76
        }
77
      }
78
    }),
79
    BaseMediaEmbedPlugin
80
  ]
81
});
82

83
// Insert an image
84
insertImage(editor, "https://example.com/image.jpg");
85

86
// Insert a media embed
87
insertMediaEmbed(editor, { 
88
  url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ" 
89
});
90
```
91

92
## Architecture
93

94
Plate Media is built around several key components:
95

96
- **Base Plugins**: Core Slate plugins for each media type (image, video, audio, file, media-embed, placeholder)
97
- **React Integration**: React-wrapped plugins with components and hooks for UI interactions
98
- **Transform System**: Consistent insert functions and element manipulation across all media types
99
- **Upload System**: Advanced placeholder-based upload with progress tracking and validation
100
- **URL Parsing**: Extensible URL parser system for detecting and embedding various media providers
101
- **State Management**: Zustand and Atom stores for complex UI interactions like image preview and upload progress
102

103
## Capabilities
104

105
### Base Media Plugins
106

107
Core Slate plugins that provide the foundation for all media handling. Each plugin defines element types, configurations, and basic transforms.
108

109
```typescript { .api }
110
const BaseImagePlugin: TSlatePlugin<ImageConfig>;
111
const BaseVideoPlugin: TSlatePlugin<VideoConfig>;
112
const BaseAudioPlugin: TSlatePlugin<AudioConfig>;
113
const BaseFilePlugin: TSlatePlugin<FileConfig>;
114
```
115

116
[Base Plugins](./base-plugins.md)
117

118
### Image Handling
119

120
Complete image management including upload, embed detection, preview functionality, and resizing capabilities.
121

122
```typescript { .api }
123
function insertImage(
124
  editor: SlateEditor, 
125
  url: ArrayBuffer | string, 
126
  options?: InsertNodesOptions
127
): void;
128

129
function insertImageFromFiles(
130
  editor: SlateEditor, 
131
  files: FileList, 
132
  options?: InsertNodesOptions
133
): void;
134

135
function isImageUrl(url: string): boolean;
136
```
137

138
[Image Management](./image.md)
139

140
### Media Embeds
141

142
Support for embedding videos and social media content from major providers including YouTube, Vimeo, Twitter, and more.
143

144
```typescript { .api }
145
const BaseMediaEmbedPlugin: TSlatePlugin<MediaEmbedConfig>;
146

147
function insertMediaEmbed(
148
  editor: SlateEditor, 
149
  { url = '' }: Partial<TMediaEmbedElement>, 
150
  options?: InsertNodesOptions
151
): void;
152

153
function parseVideoUrl(url: string): EmbedUrlData | undefined;
154
function parseTwitterUrl(url: string): EmbedUrlData | undefined;
155
```
156

157
[Media Embeds](./media-embeds.md)
158

159
### Upload System
160

161
Advanced placeholder-based upload system with file validation, progress tracking, and error handling.
162

163
```typescript { .api }
164
const BasePlaceholderPlugin: TSlatePlugin<PlaceholderConfig>;
165

166
function insertPlaceholder(
167
  editor: SlateEditor, 
168
  mediaType: string, 
169
  options?: InsertNodesOptions
170
): void;
171

172
interface UploadConfig {
173
  [K in AllowedFileType]?: MediaItemConfig;
174
}
175

176
interface MediaItemConfig {
177
  mediaType: MediaKeys;
178
  maxFileCount?: number;
179
  maxFileSize?: FileSize;
180
  minFileCount?: number;
181
}
182
```
183

184
[Upload System](./upload-system.md)
185

186
### React Components
187

188
React integration providing UI components, hooks, and state management for media interactions.
189

190
```typescript { .api }
191
const ImagePlugin: TPlatePlugin<ImageConfig>;
192
const MediaEmbedPlugin: TPlatePlugin<MediaEmbedConfig>;
193
const PlaceholderPlugin: TPlatePlugin<PlaceholderConfig>;
194

195
// Image preview functionality
196
function openImagePreview(editor: SlateEditor, element: TMediaElement): void;
197
function useImagePreview(options: { scrollSpeed: number }): ImagePreviewControls;
198

199
// Media state management
200
function useMediaState(options?: { urlParsers?: EmbedUrlParser[] }): MediaStateResult;
201
```
202

203
[React Components](./react-components.md)
204

205
## Common Types
206

207
```typescript { .api }
208
interface EmbedUrlData {
209
  id?: string;
210
  provider?: string;
211
  url?: string;
212
}
213

214
type EmbedUrlParser = (url: string) => EmbedUrlData | undefined;
215

216
interface MediaPluginOptions {
217
  isUrl?: (text: string) => boolean;
218
  transformUrl?: (url: string) => string;
219
}
220

221
interface InsertMediaOptions extends InsertNodesOptions {
222
  type?: string;
223
  getUrl?: () => Promise<string>;
224
}
225

226
type AllowedFileType = 'image' | 'video' | 'audio' | 'pdf' | 'text' | 'blob';
227
type FileSize = `${number}${'B' | 'KB' | 'MB' | 'GB'}`;
228

229
interface UploadError {
230
  code: 'INVALID_FILE_TYPE' | 'TOO_MANY_FILES' | 'INVALID_FILE_SIZE' | 'TOO_LESS_FILES' | 'TOO_LARGE';
231
  message: string;
232
}
233

234
interface ImagePreviewControls {
235
  closeProps: { onClick: () => void };
236
  currentUrlIndex: number | null;
237
  maskLayerProps: { onClick: () => void };
238
  nextDisabled: boolean;
239
  nextProps: { disabled: boolean; onClick: () => void };
240
  prevDisabled: boolean;
241
  prevProps: { disabled: boolean; onClick: () => void };
242
  scaleTextProps: { onClick: () => void };
243
  zommOutProps: { disabled: boolean; onClick: () => void };
244
  zoomInDisabled: boolean;
245
  zoomInProps: { disabled: boolean; onClick: () => void };
246
  zoomOutDisabled: boolean;
247
}
248
```