0
# HTML Serialization
1

2
HTML serialization functionality for converting Plate editor content (Slate nodes) into HTML strings. This module provides comprehensive control over HTML output formatting, class preservation, and rendering customization.
3

4
## Capabilities
5

6
### Core Serialization
7

8
Main function for converting Slate node structures to HTML with extensive customization options.
9

10
```typescript { .api }
11
/**
12
 * Convert Slate Nodes into HTML string
13
 * @param editor - Plate editor instance
14
 * @param options - Serialization configuration options
15
 * @returns HTML string representation of the nodes
16
 */
17
function serializeHTMLFromNodes(
18
  editor: PlateEditor,
19
  options: SerializeHTMLOptions
20
): string;
21

22
interface SerializeHTMLOptions {
23
  /** Plugins with renderElement or renderLeaf for custom rendering */
24
  plugins: PlatePlugin[];
25
  /** Slate nodes to convert to HTML */
26
  nodes: TDescendant[];
27
  /** Enable stripping data attributes (default: true) */
28
  stripDataAttributes?: boolean;
29
  /** List of className prefixes to preserve from being stripped out */
30
  preserveClassNames?: string[];
31
  /** Slate props to provide if the rendering depends on slate hooks */
32
  slateProps?: Partial<SlateProps>;
33
  /** Whether to strip whitespaces from serialized HTML (default: true) */
34
  stripWhitespace?: boolean;
35
}
36
```
37

38
**Usage Examples:**
39

40
```typescript
41
import { serializeHTMLFromNodes } from "@udecode/plate-html-serializer";
42

43
// Basic serialization
44
const nodes = [
45
  {
46
    type: 'p',
47
    children: [{ text: 'Hello world' }]
48
  }
49
];
50

51
const html = serializeHTMLFromNodes(editor, {
52
  plugins: myPlugins,
53
  nodes: nodes
54
});
55
// Result: "<p>Hello world</p>"
56

57
// Advanced serialization with options
58
const htmlWithOptions = serializeHTMLFromNodes(editor, {
59
  plugins: myPlugins,
60
  nodes: complexNodes,
61
  stripDataAttributes: false,           // Keep data attributes
62
  preserveClassNames: ['my-custom-'],   // Preserve classes starting with 'my-custom-'
63
  stripWhitespace: false,               // Keep whitespace formatting
64
  slateProps: {                         // Additional Slate context
65
    value: editor.children,
66
    editor: editor
67
  }
68
});
69

70
// Serializing with custom class preservation
71
const styledHtml = serializeHTMLFromNodes(editor, {
72
  plugins: myPlugins,
73
  nodes: styledNodes,
74
  preserveClassNames: ['highlight-', 'theme-', 'slate-'], // Keep these class prefixes
75
  stripDataAttributes: true // Remove slate data attributes
76
});
77
```
78

79
### HTML Processing Utilities
80

81
Low-level utilities for HTML string processing and DOM manipulation.
82

83
```typescript { .api }
84
/**
85
 * Convert HTML string into HTML element
86
 * @param rawHtml - HTML string to convert
87
 * @param stripWhitespace - Whether to strip whitespace (default: true)
88
 * @returns HTMLElement with parsed content
89
 */
90
function htmlStringToDOMNode(
91
  rawHtml: string,
92
  stripWhitespace?: boolean
93
): HTMLElement;
94
```
95

96
**Usage Example:**
97

98
```typescript
99
import { htmlStringToDOMNode } from "@udecode/plate-html-serializer";
100

101
// Convert HTML string to DOM element
102
const htmlString = '<div><p>Content</p><p>More content</p></div>';
103
const domElement = htmlStringToDOMNode(htmlString, true);
104

105
// Use with deserialization
106
const slateNodes = deserializeHTMLElement(editor, {
107
  plugins: myPlugins,
108
  element: domElement
109
});
110
```
111

112
## Serialization Process
113

114
The serialization process follows these steps:
115

116
1. **Element Processing**: Each Slate element is matched against plugin render functions
117
2. **Leaf Processing**: Text nodes with marks are processed through leaf renderers
118
3. **React Rendering**: Components are rendered to static HTML using ReactDOM
119
4. **Post-Processing**: HTML is cleaned based on configuration options:
120
   - Strip Slate data attributes (`data-slate-node`, `data-slate-type`, etc.)
121
   - Remove test IDs (`data-testid`)
122
   - Filter CSS classes (preserve only specified prefixes)
123
   - Trim whitespace if enabled
124

125
## HTML Output Customization
126

127
### Class Name Preservation
128

129
Control which CSS classes are preserved in the final HTML output:
130

131
```typescript
132
// Preserve all classes starting with specific prefixes
133
const html = serializeHTMLFromNodes(editor, {
134
  plugins: myPlugins,
135
  nodes: nodes,
136
  preserveClassNames: [
137
    'slate-',      // Keep Slate's default classes
138
    'editor-',     // Keep custom editor classes  
139
    'highlight-'   // Keep syntax highlighting classes
140
  ]
141
});
142
```
143

144
### Data Attribute Control
145

146
Choose whether to strip Slate-specific data attributes:
147

148
```typescript
149
// Keep all data attributes (useful for debugging)
150
const htmlWithData = serializeHTMLFromNodes(editor, {
151
  plugins: myPlugins,
152
  nodes: nodes,
153
  stripDataAttributes: false
154
});
155

156
// Strip data attributes for clean output (default)
157
const cleanHtml = serializeHTMLFromNodes(editor, {
158
  plugins: myPlugins,
159
  nodes: nodes,
160
  stripDataAttributes: true
161
});
162
```
163

164
### Whitespace Handling
165

166
Control whitespace processing in the output:
167

168
```typescript
169
// Preserve whitespace formatting
170
const formattedHtml = serializeHTMLFromNodes(editor, {
171
  plugins: myPlugins,
172
  nodes: nodes,
173
  stripWhitespace: false
174
});
175

176
// Remove extra whitespace for compact output (default)
177
const compactHtml = serializeHTMLFromNodes(editor, {
178
  plugins: myPlugins,
179
  nodes: nodes,
180
  stripWhitespace: true
181
});
182
```
183

184
## Integration with Plate Plugins
185

186
The serializer integrates with Plate's plugin system to provide customizable rendering:
187

188
```typescript
189
// Plugin with custom serialization
190
const myPlugin = {
191
  key: 'my-element',
192
  serialize: {
193
    element: ({ element, children }) => {
194
      if (element.type === 'my-element') {
195
        return <div className="custom-element">{children}</div>;
196
      }
197
    }
198
  },
199
  renderElement: ({ element, children }) => {
200
    if (element.type === 'my-element') {
201
      return <div className="custom-element">{children}</div>;
202
    }
203
  }
204
};
205

206
// Use plugin in serialization
207
const html = serializeHTMLFromNodes(editor, {
208
  plugins: [myPlugin],
209
  nodes: nodes
210
});
211
```