0
# HTML Deserialization
1
2
HTML deserialization functionality for converting HTML content into Plate editor format (Slate nodes). This module provides comprehensive support for parsing HTML elements, text nodes, attributes, and complex document structures.
3
4
## Capabilities
5
6
### Deserialization Plugin
7
8
Creates a Plate plugin that enables automatic HTML deserialization when content is pasted or inserted into the editor.
9
10
```typescript { .api }
11
/**
12
* Creates HTML deserializer plugin for Plate
13
* @param options - Configuration options for the deserializer
14
* @returns PlatePlugin configured for HTML deserialization
15
*/
16
function createDeserializeHTMLPlugin(
17
options?: WithDeserializeHTMLOptions
18
): PlatePlugin;
19
20
/**
21
* Higher-order function that adds HTML deserialization capability to an editor
22
* @param options - Configuration options for deserialization
23
* @returns WithOverride function for editor enhancement
24
*/
25
function withDeserializeHTML(
26
options?: WithDeserializeHTMLOptions
27
): WithOverride;
28
29
interface WithDeserializeHTMLOptions {
30
/** Array of Plate plugins to use for deserialization rules */
31
plugins?: PlatePlugin[];
32
}
33
34
/** Identifier string for the HTML deserializer */
35
const htmlDeserializerId: "HTML Deserializer";
36
```
37
38
**Usage Example:**
39
40
```typescript
41
import { createPlateEditor } from "@udecode/plate-core";
42
import { createDeserializeHTMLPlugin } from "@udecode/plate-html-serializer";
43
44
const editor = createPlateEditor({
45
plugins: [
46
createDeserializeHTMLPlugin({
47
plugins: [] // Add your custom plugins for deserialization rules
48
})
49
]
50
});
51
```
52
53
### HTML Element Deserialization
54
55
Core functions for deserializing individual HTML elements into Slate structures.
56
57
```typescript { .api }
58
/**
59
* Deserializes HTML element to Slate format
60
* @param editor - Plate editor instance
61
* @param options - Deserialization configuration
62
* @returns Deserialized Slate content
63
*/
64
function deserializeHTMLElement<T = {}>(
65
editor: PlateEditor<T>,
66
options: {
67
plugins: PlatePlugin<T>[];
68
element: HTMLElement;
69
}
70
): DeserializeHTMLReturn;
71
72
/**
73
* Deserializes HTML element or child node with comprehensive processing
74
* @param editor - Plate editor instance
75
* @param plugins - Array of Plate plugins for deserialization rules
76
* @returns Function that deserializes a node
77
*/
78
function deserializeHTMLNode<T = {}>(
79
editor: PlateEditor<T>,
80
plugins: PlatePlugin<T>[]
81
): (node: HTMLElement | ChildNode) => DeserializeHTMLReturn;
82
83
/**
84
* Deserializes HTML to Slate Element using plugin rules
85
* @param editor - Plate editor instance
86
* @param options - Element deserialization options
87
* @returns Slate Element or undefined
88
*/
89
function deserializeHTMLToElement<T = {}>(
90
editor: PlateEditor<T>,
91
options: {
92
plugins: PlatePlugin<T>[];
93
element: HTMLElement;
94
children: DeserializeHTMLChildren[];
95
}
96
): TElement | undefined;
97
```
98
99
### Text and Fragment Processing
100
101
Specialized functions for handling text nodes, fragments, and special HTML elements.
102
103
```typescript { .api }
104
/**
105
* Deserializes HTML text node to text content
106
* @param node - HTML element or child node
107
* @returns Text content or null for newlines
108
*/
109
function deserializeHTMLToText(node: HTMLElement | ChildNode): string | null;
110
111
/**
112
* Deserializes HTML body element to Fragment
113
* @param options - Fragment deserialization options
114
* @returns Slate descendant array or undefined
115
*/
116
function deserializeHTMLToFragment(options: {
117
element: HTMLElement;
118
children: DeserializeHTMLChildren[];
119
}): TDescendant[] | undefined;
120
121
/**
122
* Deserializes HTML BR elements to break lines
123
* @param node - HTML element or child node
124
* @returns Newline string or undefined
125
*/
126
function deserializeHTMLToBreak(node: HTMLElement | ChildNode): string | undefined;
127
```
128
129
### Mark Processing
130
131
Functions for handling HTML elements that represent text formatting (marks).
132
133
```typescript { .api }
134
/**
135
* Deserializes HTML to TDescendant[] with marks on Text
136
* Builds the leaf from the leaf deserializers of each plugin
137
* @param editor - Plate editor instance
138
* @param props - Mark deserialization properties
139
* @returns Array of Slate descendants with applied marks
140
*/
141
function deserializeHTMLToMarks<T = {}>(
142
editor: PlateEditor<T>,
143
props: DeserializeMarksProps<T>
144
): TDescendant[];
145
146
interface DeserializeMarksProps<T = {}> {
147
/** Array of Plate plugins for mark deserialization rules */
148
plugins: PlatePlugin<T>[];
149
/** HTML element to process for marks */
150
element: HTMLElement;
151
/** Child elements to apply marks to */
152
children: DeserializeHTMLChildren[];
153
}
154
```
155
156
**Usage Example:**
157
158
```typescript
159
import {
160
deserializeHTMLElement,
161
deserializeHTMLToDocumentFragment
162
} from "@udecode/plate-html-serializer";
163
164
// Deserialize individual HTML element
165
const htmlElement = document.createElement('div');
166
htmlElement.innerHTML = '<p><strong>Bold text</strong></p>';
167
168
const slateContent = deserializeHTMLElement(editor, {
169
plugins: myPlugins,
170
element: htmlElement.firstElementChild as HTMLElement
171
});
172
173
// Deserialize complete HTML string to document fragment
174
const htmlString = '<div><p>Paragraph 1</p><p>Paragraph 2</p></div>';
175
const documentFragment = deserializeHTMLToDocumentFragment(editor, {
176
plugins: myPlugins,
177
element: htmlString,
178
stripWhitespace: true
179
});
180
```
181
182
## Types
183
184
```typescript { .api }
185
type DeserializeHTMLChildren = ChildNode | TDescendant | string | null;
186
187
type DeserializeHTMLReturn =
188
| string
189
| null
190
| TDescendant[]
191
| TElement
192
| DeserializeHTMLChildren[];
193
194
type DeserializedHTMLElement = TDescendant;
195
```