0
# Types and Interfaces
1

2
TypeScript interfaces and types for image elements and plugin configuration.
3

4
## Capabilities
5

6
### Image Element Type
7

8
The core interface defining the structure of image elements in the Plate editor.
9

10
```typescript { .api }
11
/**
12
 * Image element interface extending Plate's base element type
13
 * Represents an image node in the editor's document structure
14
 */
15
interface TImageElement extends TElement {
16
  /** Image URL (can be data URL, blob URL, or remote URL) */
17
  url: string;
18
  /** Optional width for image sizing (CSS-compatible value) */
19
  width?: number;
20
  /** Optional caption content as descendant nodes */
21
  caption?: TDescendant[];
22
}
23
```
24

25
**Usage Examples:**
26

27
```typescript
28
import { TImageElement } from "@udecode/plate-image";
29

30
// Create image element data
31
const imageElement: TImageElement = {
32
  type: 'img',
33
  url: 'https://example.com/image.jpg',
34
  width: 400,
35
  caption: [{ text: 'Sample image caption' }],
36
  children: [{ text: '' }] // Required by TElement
37
};
38

39
// Type-safe access to image properties
40
function processImageElement(element: TImageElement) {
41
  console.log(`Image URL: ${element.url}`);
42
  if (element.width) {
43
    console.log(`Width: ${element.width}px`);
44
  }
45
  if (element.caption) {
46
    console.log(`Has caption with ${element.caption.length} nodes`);
47
  }
48
}
49
```
50

51
### Plugin Configuration Interface
52

53
Interface defining the configuration options for the image plugin.
54

55
```typescript { .api }
56
/**
57
 * Configuration interface for the image plugin
58
 * All properties are optional with sensible defaults
59
 */
60
interface ImagePlugin {
61
  /**
62
   * Custom image upload function
63
   * Called when user pastes/drops image files
64
   * @param dataUrl - Base64 data URL or ArrayBuffer of the image
65
   * @returns Promise resolving to uploaded image URL or synchronous URL
66
   */
67
  uploadImage?: (
68
    dataUrl: string | ArrayBuffer
69
  ) => Promise<string | ArrayBuffer> | string | ArrayBuffer;
70

71
  /**
72
   * Disable automatic file upload on paste/drop operations
73
   * When true, image files won't be processed automatically
74
   * @default false
75
   */
76
  disableUploadInsert?: boolean;
77

78
  /**
79
   * Disable automatic URL embedding when pasting image URLs
80
   * When true, image URLs will be treated as regular text
81
   * @default false
82
   */
83
  disableEmbedInsert?: boolean;
84
}
85
```
86

87
**Usage Examples:**
88

89
```typescript
90
import { ImagePlugin } from "@udecode/plate-image";
91

92
// Minimal configuration
93
const basicConfig: ImagePlugin = {};
94

95
// Configuration with custom upload
96
const uploadConfig: ImagePlugin = {
97
  uploadImage: async (dataUrl) => {
98
    try {
99
      const response = await fetch('/api/images', {
100
        method: 'POST',
101
        headers: { 'Content-Type': 'application/json' },
102
        body: JSON.stringify({ imageData: dataUrl })
103
      });
104
      const result = await response.json();
105
      return result.imageUrl;
106
    } catch (error) {
107
      console.error('Upload failed:', error);
108
      throw error;
109
    }
110
  }
111
};
112

113
// Configuration with disabled features
114
const restrictedConfig: ImagePlugin = {
115
  disableUploadInsert: true,  // No file uploads
116
  disableEmbedInsert: false,  // Still allow URL embedding
117
};
118

119
// Complete configuration example
120
const fullConfig: ImagePlugin = {
121
  async uploadImage(dataUrl) {
122
    // Handle both string and ArrayBuffer inputs
123
    const imageData = typeof dataUrl === 'string' ? dataUrl : dataUrl;
124
    
125
    // Custom upload logic with error handling
126
    try {
127
      const uploadResult = await uploadToCloudinary(imageData);
128
      return uploadResult.secure_url;
129
    } catch (error) {
130
      // Fallback to data URL if upload fails
131
      return dataUrl;
132
    }
133
  },
134
  disableUploadInsert: false,
135
  disableEmbedInsert: false,
136
};
137
```
138

139
## Type Usage Patterns
140

141
### Working with Image Elements
142

143
```typescript
144
import { TImageElement, useImageElement } from "@udecode/plate-image";
145
import { setNodes, findNodePath } from "@udecode/plate-core";
146

147
// Hook usage in components
148
function MyImageComponent() {
149
  const element = useImageElement(); // Returns TImageElement
150
  
151
  // Type-safe property access
152
  const imageUrl = element.url;
153
  const imageWidth = element.width || '100%';
154
  const hasCaption = element.caption && element.caption.length > 0;
155
  
156
  return (
157
    <img 
158
      src={imageUrl}
159
      style={{ width: imageWidth }}
160
      alt={hasCaption ? 'Image with caption' : 'Image'}
161
    />
162
  );
163
}
164

165
// Programmatic element manipulation
166
function updateImageWidth(editor: PlateEditor, newWidth: number) {
167
  const element = useImageElement();
168
  const path = findNodePath(editor, element);
169
  
170
  if (path) {
171
    setNodes<TImageElement>(
172
      editor,
173
      { width: newWidth },
174
      { at: path }
175
    );
176
  }
177
}
178
```
179

180
### Plugin Configuration Patterns
181

182
```typescript
183
import { createImagePlugin, ImagePlugin } from "@udecode/plate-image";
184

185
// Factory function for creating configured plugins
186
function createCustomImagePlugin(uploadEndpoint: string): ImagePlugin {
187
  return {
188
    uploadImage: async (dataUrl) => {
189
      const response = await fetch(uploadEndpoint, {
190
        method: 'POST',
191
        body: JSON.stringify({ image: dataUrl }),
192
        headers: { 'Content-Type': 'application/json' }
193
      });
194
      return response.json().then(data => data.url);
195
    }
196
  };
197
}
198

199
// Conditional configuration
200
function createImagePluginForEnvironment(isDevelopment: boolean): ImagePlugin {
201
  if (isDevelopment) {
202
    return {
203
      // In development, just use data URLs
204
      uploadImage: (dataUrl) => Promise.resolve(dataUrl)
205
    };
206
  }
207
  
208
  return {
209
    uploadImage: async (dataUrl) => {
210
      // Production upload logic
211
      return await uploadToProduction(dataUrl);
212
    }
213
  };
214
}
215
```