0
# @udecode/plate-image
1
2
The @udecode/plate-image package provides a comprehensive image plugin for the Plate rich text editor framework, built on top of Slate.js. It enables developers to embed, upload, and manage images within rich text documents with advanced features including drag-and-drop support, resizing capabilities, clipboard paste functionality, and automatic image upload handling.
3
4
## Package Information
5
6
- **Package Name**: @udecode/plate-image
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @udecode/plate-image`
10
11
## Core Imports
12
13
```typescript
14
import { createImagePlugin, ELEMENT_IMAGE, TImageElement } from "@udecode/plate-image";
15
```
16
17
For individual components and utilities:
18
19
```typescript
20
import {
21
Image,
22
insertImage,
23
useImageElement,
24
useImageCaptionString,
25
isImageUrl,
26
withImage,
27
withImageUpload,
28
withImageEmbed
29
} from "@udecode/plate-image";
30
```
31
32
For component hooks and store management:
33
34
```typescript
35
import {
36
useImageCaption,
37
useImageCaptionState,
38
useImageResizable,
39
imageStore,
40
useImageStore,
41
imageGlobalStore
42
} from "@udecode/plate-image";
43
```
44
45
For all types and interfaces:
46
47
```typescript
48
import {
49
TImageElement,
50
ImagePlugin,
51
ImageCaptionProps,
52
ImageResizableProps,
53
ImageCaptionTextareaProps
54
} from "@udecode/plate-image";
55
```
56
57
## Basic Usage
58
59
```typescript
60
import { createImagePlugin, ELEMENT_IMAGE } from "@udecode/plate-image";
61
import { createPlateEditor } from "@udecode/plate-core";
62
63
// Create editor with image plugin
64
const editor = createPlateEditor({
65
plugins: [
66
createImagePlugin({
67
options: {
68
uploadImage: async (dataUrl) => {
69
// Custom upload logic
70
const response = await fetch('/api/upload', {
71
method: 'POST',
72
body: JSON.stringify({ image: dataUrl }),
73
});
74
return response.json().url;
75
}
76
}
77
})
78
]
79
});
80
81
// Insert an image programmatically
82
import { insertImage } from "@udecode/plate-image";
83
insertImage(editor, "https://example.com/image.jpg");
84
```
85
86
## Architecture
87
88
The @udecode/plate-image plugin is built around several key components:
89
90
- **Plugin Factory**: `createImagePlugin` provides the main plugin configuration and behavior
91
- **Editor Enhancements**: Higher-order functions (`withImage`, `withImageUpload`, `withImageEmbed`) that extend editor functionality
92
- **React Components**: Complete set of UI components for rendering and interacting with images
93
- **Transforms**: Functions for programmatically manipulating image elements
94
- **Hooks**: React hooks for accessing image state and functionality
95
- **Type System**: Full TypeScript integration with proper type definitions
96
- **Store Management**: Centralized state management for image-specific behavior
97
98
## Capabilities
99
100
### Plugin Configuration
101
102
Core plugin factory and configuration options for integrating image functionality into Plate editors.
103
104
```typescript { .api }
105
function createImagePlugin<ImagePlugin>(options?: {
106
key?: string;
107
isElement?: boolean;
108
isVoid?: boolean;
109
options?: ImagePlugin;
110
}): PlatePlugin<ImagePlugin>;
111
112
const ELEMENT_IMAGE: string;
113
```
114
115
[Plugin Configuration](./plugin-configuration.md)
116
117
### Image Types and Interfaces
118
119
TypeScript interfaces and types for image elements and plugin configuration.
120
121
```typescript { .api }
122
interface TImageElement extends TElement {
123
url: string;
124
width?: number;
125
caption?: TDescendant[];
126
}
127
128
interface ImagePlugin {
129
uploadImage?: (dataUrl: string | ArrayBuffer) => Promise<string | ArrayBuffer> | string | ArrayBuffer;
130
disableUploadInsert?: boolean;
131
disableEmbedInsert?: boolean;
132
}
133
```
134
135
[Types and Interfaces](./types-interfaces.md)
136
137
### Editor Enhancements
138
139
Higher-order functions that enhance the Plate editor with image-specific functionality including upload handling and URL embedding.
140
141
```typescript { .api }
142
function withImage<V extends Value = Value, E extends PlateEditor<V> = PlateEditor<V>>(
143
editor: E,
144
plugin: WithPlatePlugin<ImagePlugin, V, E>
145
): E;
146
147
function withImageUpload<V extends Value = Value, E extends PlateEditor<V> = PlateEditor<V>>(
148
editor: E,
149
plugin: WithPlatePlugin<ImagePlugin, V, E>
150
): E;
151
152
function withImageEmbed<V extends Value = Value, E extends PlateEditor<V> = PlateEditor<V>>(
153
editor: E,
154
plugin: WithPlatePlugin<ImagePlugin, V, E>
155
): E;
156
```
157
158
[Editor Enhancements](./editor-enhancements.md)
159
160
### React Components
161
162
Complete set of React components for rendering images with captions, resizing handles, and interactive features.
163
164
```typescript { .api }
165
const Image: {
166
Root: React.ComponentType<any>;
167
Caption: React.ComponentType<ImageCaptionProps>;
168
Img: React.ComponentType<any>;
169
Resizable: React.ComponentType<ImageResizableProps>;
170
CaptionTextarea: React.ComponentType<ImageCaptionTextareaProps>;
171
};
172
173
interface ImageCaptionProps extends HTMLPropsAs<'figcaption'> {
174
readOnly?: boolean;
175
}
176
177
interface ImageResizableProps extends Omit<ResizableProps, 'as'>, AsProps<'div'> {
178
align?: 'left' | 'center' | 'right';
179
readOnly?: boolean;
180
}
181
```
182
183
[React Components](./react-components.md)
184
185
### Hooks and State Management
186
187
React hooks for accessing image element data, managing captions, and integrating with the image store system.
188
189
```typescript { .api }
190
function useImageElement(): TImageElement;
191
function useImageCaptionString(): string;
192
```
193
194
[Hooks and State](./hooks-state.md)
195
196
### Transforms and Utilities
197
198
Functions for programmatically inserting images and utility functions for image URL validation.
199
200
```typescript { .api }
201
function insertImage<V extends Value>(
202
editor: PlateEditor<V>,
203
url: string | ArrayBuffer
204
): void;
205
206
function isImageUrl(url: string): boolean;
207
```
208
209
[Transforms and Utilities](./transforms-utilities.md)
210
211
## Type Definitions
212
213
```typescript { .api }
214
// Core Plate framework types (from @udecode/plate-core)
215
interface TElement {
216
type: string;
217
children: TDescendant[];
218
}
219
220
interface TDescendant {
221
[key: string]: any;
222
}
223
224
interface PlateEditor<V extends Value = Value> {
225
[key: string]: any;
226
}
227
228
interface Value {
229
[key: string]: any;
230
}
231
232
interface WithPlatePlugin<T, V extends Value, E extends PlateEditor<V>> {
233
options: T;
234
[key: string]: any;
235
}
236
237
// HTML and component prop types
238
interface HTMLPropsAs<T extends keyof JSX.IntrinsicElements> {
239
[key: string]: any;
240
}
241
242
interface AsProps<T extends keyof JSX.IntrinsicElements> {
243
as?: T;
244
}
245
246
// External library types
247
interface ResizableProps {
248
[key: string]: any;
249
}
250
```