0
# Image Management
1

2
Complete image management system providing upload capabilities, automatic embed detection, preview functionality, zoom controls, and URL validation. Supports both programmatic insertion and user interactions like drag & drop and paste operations.
3

4
## Capabilities
5

6
### Image Insertion
7

8
Core functions for inserting images into the editor.
9

10
#### Insert Image
11

12
```typescript { .api }
13
/**
14
 * Inserts an image element at the current selection
15
 * @param editor - Slate editor instance
16
 * @param url - Image URL or ArrayBuffer data
17
 * @param options - Optional insertion configuration
18
 */
19
function insertImage(
20
  editor: SlateEditor, 
21
  url: ArrayBuffer | string, 
22
  options?: InsertNodesOptions
23
): void;
24
```
25

26
**Usage Example:**
27

28
```typescript
29
import { insertImage } from "@udecode/plate-media";
30

31
// Insert image from URL
32
insertImage(editor, "https://example.com/image.jpg");
33

34
// Insert image from file data
35
const fileData = await file.arrayBuffer();
36
insertImage(editor, fileData, { 
37
  at: [0, 0] // Specific insertion point
38
});
39
```
40

41
#### Insert Images from Files
42

43
```typescript { .api }
44
/**
45
 * Processes FileList and inserts images after upload processing
46
 * Handles multiple files and integrates with upload configuration
47
 * @param editor - Slate editor instance
48
 * @param files - FileList from input or drag & drop
49
 * @param options - Optional insertion configuration
50
 */
51
function insertImageFromFiles(
52
  editor: SlateEditor, 
53
  files: FileList, 
54
  options?: InsertNodesOptions
55
): void;
56
```
57

58
**Usage Example:**
59

60
```typescript
61
import { insertImageFromFiles } from "@udecode/plate-media";
62

63
// Handle file input change
64
const handleFileChange = (event: ChangeEvent<HTMLInputElement>) => {
65
  if (event.target.files) {
66
    insertImageFromFiles(editor, event.target.files);
67
  }
68
};
69

70
// Handle drag & drop
71
const handleDrop = (event: DragEvent) => {
72
  event.preventDefault();
73
  if (event.dataTransfer?.files) {
74
    insertImageFromFiles(editor, event.dataTransfer.files);
75
  }
76
};
77
```
78

79
### URL Validation
80

81
Utility for detecting image URLs based on file extensions.
82

83
```typescript { .api }
84
/**
85
 * Validates if a URL points to an image based on file extension
86
 * Supports comprehensive list of image formats
87
 * @param url - URL string to validate
88
 * @returns Boolean indicating if URL is likely an image
89
 */
90
function isImageUrl(url: string): boolean;
91
```
92

93
**Supported Extensions:**
94
- Common formats: jpg, jpeg, png, gif, svg, webp, bmp, tiff, tif, ico
95
- RAW formats: cr2, raw 
96
- Professional formats: psd, ai, eps, dxf, xcf
97
- Legacy formats: pcx, tga, xbm, xpm
98
- And many more: Complete list includes 100+ image formats and extensions
99

100
**Usage Example:**
101

102
```typescript
103
import { isImageUrl } from "@udecode/plate-media";
104

105
const checkUrl = (url: string) => {
106
  if (isImageUrl(url)) {
107
    // Handle as image
108
    insertImage(editor, url);
109
  } else {
110
    // Handle as regular link
111
    insertLink(editor, url);
112
  }
113
};
114

115
checkUrl("https://example.com/photo.jpg"); // true
116
checkUrl("https://example.com/document.pdf"); // false
117
```
118

119
## React Integration
120

121
React-specific image functionality including components, hooks, and state management.
122

123
### Image Preview System
124

125
Advanced image preview functionality with zoom, navigation, and keyboard controls.
126

127
#### Image Preview Store
128

129
```typescript { .api }
130
/**
131
 * Zustand store managing image preview state across the application
132
 */
133
interface ImagePreviewStore {
134
  // State
135
  currentPreview: PreviewItem | null;
136
  previewList: PreviewItem[];
137
  openEditorId: string | null;
138
  scale: number;
139
  translate: { x: number; y: number };
140
  isEditingScale: boolean;
141
  boundingClientRect: DOMRect | null;
142
  
143
  // Actions
144
  close(): void;
145
  
146
  // Selectors
147
  isOpen(editorId: string): boolean;
148
}
149

150
interface PreviewItem {
151
  id: string;
152
  url: string;
153
  element: TMediaElement;
154
}
155
```
156

157
#### Open Image Preview
158

159
```typescript { .api }
160
/**
161
 * Opens image preview overlay for the specified image element
162
 * @param editor - Slate editor instance
163
 * @param element - Media element to preview
164
 */
165
function openImagePreview(editor: SlateEditor, element: TMediaElement): void;
166
```
167

168
#### Image Preview Hook
169

170
```typescript { .api }
171
/**
172
 * Complete image preview functionality with controls and keyboard shortcuts
173
 * @param options - Configuration options
174
 * @returns Complete preview control props and handlers
175
 */
176
function useImagePreview(options: { 
177
  scrollSpeed: number 
178
}): ImagePreviewControls;
179

180
interface ImagePreviewControls {
181
  // Navigation
182
  canGoNext: boolean;
183
  canGoPrevious: boolean;
184
  goNext: () => void;
185
  goPrevious: () => void;
186
  
187
  // Zoom controls
188
  canZoomIn: boolean;
189
  canZoomOut: boolean;
190
  zoomIn: () => void;
191
  zoomOut: () => void;
192
  
193
  // Pan controls
194
  onMouseDown: (event: MouseEvent) => void;
195
  onWheel: (event: WheelEvent) => void;
196
  
197
  // Keyboard shortcuts
198
  onKeyDown: (event: KeyboardEvent) => void;
199
  
200
  // State
201
  scale: number;
202
  translate: { x: number; y: number };
203
}
204
```
205

206
**Usage Example:**
207

208
```typescript
209
import { useImagePreview, openImagePreview } from "@udecode/plate-media/react";
210

211
const ImagePreviewComponent = () => {
212
  const controls = useImagePreview({ scrollSpeed: 0.1 });
213
  
214
  return (
215
    <div 
216
      onKeyDown={controls.onKeyDown}
217
      onWheel={controls.onWheel}
218
      onMouseDown={controls.onMouseDown}
219
      tabIndex={0}
220
    >
221
      <div>
222
        <button 
223
          onClick={controls.zoomIn} 
224
          disabled={!controls.canZoomIn}
225
        >
226
          Zoom In
227
        </button>
228
        <button 
229
          onClick={controls.zoomOut} 
230
          disabled={!controls.canZoomOut}
231
        >
232
          Zoom Out  
233
        </button>
234
      </div>
235
      
236
      <div>
237
        <button 
238
          onClick={controls.goPrevious} 
239
          disabled={!controls.canGoPrevious}
240
        >
241
          Previous
242
        </button>
243
        <button 
244
          onClick={controls.goNext} 
245
          disabled={!controls.canGoNext}
246
        >
247
          Next
248
        </button>
249
      </div>
250
      
251
      <div 
252
        style={{
253
          transform: `scale(${controls.scale}) translate(${controls.translate.x}px, ${controls.translate.y}px)`
254
        }}
255
      >
256
        {/* Image content */}
257
      </div>
258
    </div>
259
  );
260
};
261
```
262

263
### Zoom Functionality
264

265
Dedicated zoom controls for image preview.
266

267
```typescript { .api }
268
/**
269
 * Provides zoom in/out functionality with predefined zoom levels
270
 * @returns Zoom control functions
271
 */
272
function useZoom(): {
273
  zoomIn: () => void;
274
  zoomOut: () => void;
275
};
276
```
277

278
**Zoom Levels:** 0, 0.5, 1, 1.5, 2
279

280
### Image Components
281

282
React primitive components for image rendering and interaction.
283

284
#### Image Component
285

286
```typescript { .api }
287
/**
288
 * Primitive image component with drag and preview functionality
289
 * Provides double-click to open preview and draggable behavior
290
 */
291
const Image: React.ComponentType;
292

293
/**
294
 * Hook providing image component props and handlers
295
 * @returns Props for image element including drag and preview handlers
296
 */
297
function useImage(): {
298
  onDoubleClick: () => void;
299
  draggable: boolean;
300
  onDragStart: (event: DragEvent) => void;
301
};
302
```
303

304
#### Preview Image Component
305

306
```typescript { .api }
307
/**
308
 * Primitive component for preview overlay image
309
 * Handles click-to-zoom and transform styles
310
 */
311
const PreviewImage: React.ComponentType;
312

313
/**
314
 * Hook providing preview image props with zoom and transform functionality
315
 * @returns Props for preview image including click handlers and styles
316
 */
317
function usePreviewImage(): {
318
  onClick: () => void;
319
  style: CSSProperties;
320
  cursor: string;
321
};
322
```
323

324
#### Scale Input Hook
325

326
```typescript { .api }
327
/**
328
 * Hook for scale input management in preview mode
329
 * Provides auto-focus, validation, and keyboard handling
330
 * @returns Input props for scale editing
331
 */
332
function useScaleInput(): {
333
  value: string;
334
  onChange: (event: ChangeEvent<HTMLInputElement>) => void;
335
  onKeyDown: (event: KeyboardEvent) => void;
336
  onBlur: () => void;
337
  autoFocus: boolean;
338
};
339
```
340

341
## Configuration
342

343
### Image-Specific Configuration
344

345
Extended configuration options specific to image handling.
346

347
```typescript { .api }
348
interface ImageConfig extends MediaPluginOptions {
349
  /** Disable automatic image insertion when pasting URLs */
350
  disableEmbedInsert?: boolean;
351
  /** Disable image upload functionality */
352
  disableUploadInsert?: boolean;
353
  /** Upload function for handling image files */
354
  uploadImage?: (dataUrl: ArrayBuffer | string) => Promise<string> | string;
355
}
356
```
357

358
**Usage Example:**
359

360
```typescript
361
import { BaseImagePlugin } from "@udecode/plate-media";
362

363
const imageConfig: ImageConfig = {
364
  disableEmbedInsert: false,
365
  disableUploadInsert: false,
366
  uploadImage: async (file) => {
367
    const formData = new FormData();
368
    formData.append('image', file);
369
    
370
    const response = await fetch('/api/upload-image', {
371
      method: 'POST',
372
      body: formData
373
    });
374
    
375
    const result = await response.json();
376
    return result.url;
377
  },
378
  isUrl: (text) => /^https?:\/\/.+\.(jpg|jpeg|png|gif|webp)$/i.test(text),
379
  transformUrl: (url) => `${url}?width=800&quality=85`
380
};
381

382
const editor = createSlateEditor({
383
  plugins: [
384
    BaseImagePlugin.configure({
385
      options: imageConfig
386
    })
387
  ]
388
});
389
```