0
# Plate HTML Serializer
1

2
The Plate HTML Serializer provides bidirectional conversion between Plate editor content (Slate nodes) and HTML format for the Plate rich text editor framework. It enables seamless integration between HTML content and Plate's internal Slate data structure, supporting both serialization (Slate → HTML) and deserialization (HTML → Slate).
3

4
## Package Information
5

6
- **Package Name**: @udecode/plate-html-serializer
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @udecode/plate-html-serializer`
10

11
## Core Imports
12

13
```typescript
14
import { 
15
  // Plugin functions
16
  createDeserializeHTMLPlugin,
17
  withDeserializeHTML,
18
  // Serialization functions
19
  serializeHTMLFromNodes,
20
  htmlStringToDOMNode,
21
  // Deserialization functions
22
  deserializeHTMLToDocumentFragment,
23
  deserializeHTMLElement,
24
  deserializeHTMLNode,
25
  deserializeHTMLToElement,
26
  deserializeHTMLToText,
27
  deserializeHTMLToFragment,
28
  deserializeHTMLToMarks,
29
  deserializeHTMLToBreak,
30
  // Constants
31
  htmlDeserializerId
32
} from "@udecode/plate-html-serializer";
33
```
34

35
For CommonJS:
36

37
```javascript
38
const { 
39
  // Plugin functions
40
  createDeserializeHTMLPlugin,
41
  withDeserializeHTML,
42
  // Serialization functions
43
  serializeHTMLFromNodes,
44
  htmlStringToDOMNode,
45
  // Deserialization functions
46
  deserializeHTMLToDocumentFragment,
47
  deserializeHTMLElement,
48
  deserializeHTMLNode,
49
  deserializeHTMLToElement,
50
  deserializeHTMLToText,
51
  deserializeHTMLToFragment,
52
  deserializeHTMLToMarks,
53
  deserializeHTMLToBreak,
54
  // Constants
55
  htmlDeserializerId
56
} = require("@udecode/plate-html-serializer");
57
```
58

59
## Basic Usage
60

61
```typescript
62
import { createPlateEditor } from "@udecode/plate-core";
63
import { 
64
  createDeserializeHTMLPlugin,
65
  serializeHTMLFromNodes,
66
  deserializeHTMLToDocumentFragment
67
} from "@udecode/plate-html-serializer";
68

69
// Create editor with HTML deserialization support
70
const editor = createPlateEditor({
71
  plugins: [
72
    createDeserializeHTMLPlugin({
73
      plugins: [] // Add your Plate plugins here for deserialization rules
74
    })
75
  ]
76
});
77

78
// Serialize Slate nodes to HTML
79
const nodes = [{ type: 'p', children: [{ text: 'Hello world' }] }];
80
const html = serializeHTMLFromNodes(editor, {
81
  plugins: [], // Add your Plate plugins here for rendering
82
  nodes: nodes,
83
  stripDataAttributes: true,
84
  stripWhitespace: true
85
});
86
console.log(html); // "<p>Hello world</p>"
87

88
// Deserialize HTML string to Slate nodes
89
const htmlString = '<p>Hello <strong>world</strong></p>';
90
const slateNodes = deserializeHTMLToDocumentFragment(editor, {
91
  plugins: [], // Add your Plate plugins here for deserialization rules
92
  element: htmlString,
93
  stripWhitespace: true
94
});
95
console.log(slateNodes);
96
// [{ type: 'p', children: [{ text: 'Hello ' }, { text: 'world', bold: true }] }]
97
```
98

99
## Architecture
100

101
The Plate HTML Serializer is built around two core modules:
102

103
- **Deserializer**: Converts HTML elements and strings into Slate node structures, with support for elements, marks, text nodes, and fragments
104
- **Serializer**: Converts Slate node structures into HTML strings, with customizable rendering and formatting options
105
- **Plugin System**: Integrates with Plate's plugin architecture for extensible serialization/deserialization rules
106
- **Type Safety**: Full TypeScript support with comprehensive type definitions for all operations
107

108
## Capabilities
109

110
### HTML Deserialization
111

112
Core functionality for converting HTML content into Slate node structures, including plugin integration and low-level processing utilities.
113

114
```typescript { .api }
115
function createDeserializeHTMLPlugin(
116
  options?: WithDeserializeHTMLOptions
117
): PlatePlugin;
118

119
function withDeserializeHTML(
120
  options?: WithDeserializeHTMLOptions  
121
): WithOverride;
122

123
function deserializeHTMLElement<T = {}>(
124
  editor: PlateEditor<T>,
125
  options: { plugins: PlatePlugin<T>[]; element: HTMLElement; }
126
): DeserializeHTMLReturn;
127

128
function deserializeHTMLNode<T = {}>(
129
  editor: PlateEditor<T>,
130
  plugins: PlatePlugin<T>[]
131
): (node: HTMLElement | ChildNode) => DeserializeHTMLReturn;
132

133
function deserializeHTMLToElement<T = {}>(
134
  editor: PlateEditor<T>,
135
  options: {
136
    plugins: PlatePlugin<T>[];
137
    element: HTMLElement;
138
    children: DeserializeHTMLChildren[];
139
  }
140
): TElement | undefined;
141

142
function deserializeHTMLToText(
143
  node: HTMLElement | ChildNode
144
): string | null;
145

146
function deserializeHTMLToFragment(options: {
147
  element: HTMLElement;
148
  children: DeserializeHTMLChildren[];
149
}): TDescendant[] | undefined;
150

151
function deserializeHTMLToMarks<T = {}>(
152
  editor: PlateEditor<T>,
153
  props: DeserializeMarksProps<T>
154
): TDescendant[];
155

156
function deserializeHTMLToBreak(
157
  node: HTMLElement | ChildNode
158
): string | undefined;
159

160
interface WithDeserializeHTMLOptions {
161
  plugins?: PlatePlugin[];
162
}
163

164
const htmlDeserializerId: "HTML Deserializer";
165
```
166

167
[HTML Deserialization](./deserialization.md)
168

169
### HTML Serialization
170

171
Convert Slate nodes to HTML strings with extensive customization options for rendering, class preservation, and formatting.
172

173
```typescript { .api }
174
function serializeHTMLFromNodes(
175
  editor: PlateEditor,
176
  options: SerializeHTMLOptions
177
): string;
178

179
function htmlStringToDOMNode(
180
  rawHtml: string,
181
  stripWhitespace?: boolean
182
): HTMLElement;
183
```
184

185
[HTML Serialization](./serialization.md)
186

187
### HTML Document Processing
188

189
Low-level utilities for processing HTML elements, fragments, and document structures into Slate-compatible formats.
190

191
```typescript { .api }
192
function deserializeHTMLToDocumentFragment<T = {}>(
193
  editor: PlateEditor<T>,
194
  options: DocumentFragmentOptions<T>
195
): TDescendant[];
196
```
197

198
[Document Processing](./document-processing.md)
199

200
## Types
201

202
```typescript { .api }
203
// Deserialization types
204
type DeserializeHTMLChildren = ChildNode | TDescendant | string | null;
205

206
type DeserializeHTMLReturn = 
207
  | string 
208
  | null 
209
  | TDescendant[] 
210
  | TElement 
211
  | DeserializeHTMLChildren[];
212

213
type DeserializedHTMLElement = TDescendant;
214

215
interface DeserializeMarksProps<T = {}> {
216
  plugins: PlatePlugin<T>[];
217
  element: HTMLElement;
218
  children: DeserializeHTMLChildren[];
219
}
220

221
interface WithDeserializeHTMLOptions {
222
  plugins?: PlatePlugin[];
223
}
224

225
interface DocumentFragmentOptions<T> {
226
  plugins: PlatePlugin<T>[];
227
  element: HTMLElement | string;
228
  stripWhitespace?: boolean;
229
}
230

231
// Serialization types
232
interface SerializeHTMLOptions {
233
  plugins: PlatePlugin[];
234
  nodes: TDescendant[];
235
  stripDataAttributes?: boolean;
236
  preserveClassNames?: string[];
237
  slateProps?: Partial<SlateProps>;
238
  stripWhitespace?: boolean;
239
}
240
```