0
# Plugin Configuration
1

2
Core plugin factory and configuration options for integrating image functionality into Plate editors.
3

4
## Capabilities
5

6
### Create Image Plugin
7

8
Creates the main image plugin with configurable options for upload handling and behavior customization.
9

10
```typescript { .api }
11
/**
12
 * Creates an image plugin for Plate editor with configurable options
13
 * @param options - Plugin configuration options
14
 * @returns Configured Plate plugin for image functionality
15
 */
16
function createImagePlugin(options?: {
17
  options?: ImagePlugin;
18
}): PlatePlugin<ImagePlugin>;
19
```
20

21
**Usage Examples:**
22

23
```typescript
24
import { createImagePlugin } from "@udecode/plate-image";
25

26
// Basic plugin setup
27
const imagePlugin = createImagePlugin();
28

29
// Plugin with custom upload function
30
const imagePluginWithUpload = createImagePlugin({
31
  options: {
32
    uploadImage: async (dataUrl) => {
33
      const formData = new FormData();
34
      formData.append('image', dataUrl);
35
      const response = await fetch('/api/upload', {
36
        method: 'POST',
37
        body: formData,
38
      });
39
      const result = await response.json();
40
      return result.url;
41
    }
42
  }
43
});
44

45
// Plugin with disabled features
46
const restrictedImagePlugin = createImagePlugin({
47
  options: {
48
    disableUploadInsert: true,
49
    disableEmbedInsert: false,
50
  }
51
});
52
```
53

54
### Element Type Constant
55

56
The string constant used to identify image elements in the Plate editor.
57

58
```typescript { .api }
59
/**
60
 * Element type constant for image elements ('img')
61
 * Used throughout the plugin system to identify image nodes
62
 */
63
const ELEMENT_IMAGE: string;
64
```
65

66
**Usage Examples:**
67

68
```typescript
69
import { ELEMENT_IMAGE, getPluginType } from "@udecode/plate-image";
70
import { getBlockAbove } from "@udecode/plate-core";
71

72
// Check if current selection is an image
73
const entry = getBlockAbove(editor, {
74
  match: { type: getPluginType(editor, ELEMENT_IMAGE) },
75
});
76

77
// Use in plugin configuration
78
const customImagePlugin = {
79
  key: ELEMENT_IMAGE,
80
  isElement: true,
81
  isVoid: true,
82
  // ... other configuration
83
};
84
```
85

86
## Plugin Options Interface
87

88
The plugin accepts an `ImagePlugin` configuration object with the following optional properties:
89

90
```typescript { .api }
91
interface ImagePlugin {
92
  /**
93
   * Custom image upload function
94
   * Receives base64 dataUrl and should return uploaded image URL
95
   */
96
  uploadImage?: (
97
    dataUrl: string | ArrayBuffer
98
  ) => Promise<string | ArrayBuffer> | string | ArrayBuffer;
99

100
  /**
101
   * Disable automatic file upload on paste/drop
102
   * Default: false
103
   */
104
  disableUploadInsert?: boolean;
105

106
  /**
107
   * Disable automatic URL embedding
108
   * Default: false
109
   */
110
  disableEmbedInsert?: boolean;
111
}
112
```
113

114
## Plugin Behavior
115

116
The image plugin provides several automatic behaviors when integrated:
117

118
1. **HTML Deserialization**: Automatically converts `<img>` tags to image elements when pasting HTML content
119
2. **Keyboard Navigation**: Handles down arrow key to focus caption from image element
120
3. **Event Handling**: Provides keyboard shortcuts and navigation between image and caption
121
4. **Element Configuration**: Sets up image elements as void (non-editable content) elements
122

123
## Integration with Plate Core
124

125
The plugin integrates seamlessly with Plate's plugin system:
126

127
```typescript
128
import { createPlateEditor } from "@udecode/plate-core";
129
import { createImagePlugin } from "@udecode/plate-image";
130

131
const editor = createPlateEditor({
132
  plugins: [
133
    // Other plugins...
134
    createImagePlugin({
135
      options: {
136
        uploadImage: async (dataUrl) => {
137
          // Your upload logic here
138
          return uploadedUrl;
139
        }
140
      }
141
    }),
142
    // More plugins...
143
  ]
144
});
145
```