HTML

Convert Plate content to HTML and vice-versa.

This guide covers converting Plate editor content to HTML (serializeHtml) and parsing HTML back into Plate's format (editor.api.html.deserialize).

components/demo.tsx

'use client';

import * as React from 'react';

import { Plate } from '@udecode/plate/react';

import { editorPlugins } from '@/components/editor/plugins/editor-plugins';
import { useCreateEditor } from '@/components/editor/use-create-editor';
import { Editor, EditorContainer } from '@/components/ui/editor';

import { DEMO_VALUES } from './values/demo-values';

export default function Demo({ id }: { id: string }) {
  const editor = useCreateEditor({
    plugins: [...editorPlugins],
    value: DEMO_VALUES[id],
  });

  return (
    <Plate editor={editor}>
      <EditorContainer variant="demo">
        <Editor />
      </EditorContainer>
    </Plate>
  );
}

Plate to HTML

Convert Plate editor content (Slate nodes) into an HTML string. This is often done server-side.

View Server-Side Example

Key Server-Side Constraint

When using serializeHtml or other Plate utilities in a server environment (Node.js, RSC), you must not import from /react subpaths of any @udecode/plate* package. Always use the base imports (e.g., @udecode/plate-basic-elements instead of @udecode/plate-basic-elements/react).

This means you should use createSlateEditor from @udecode/plate for server-side editor instances, not usePlateEditor or createPlateEditor from @udecode/plate/react.

Basic Usage

Provide a server-side editor instance and a mapping of your Plate components to their static HTML rendering counterparts.

lib/generate-html.ts

import { createSlateEditor, serializeHtml } from '@udecode/plate'; // Base import
// Import base plugins (NOT from /react paths)
import { BaseHeadingPlugin } from '@udecode/plate-heading';
// Import your STATIC components for rendering
import { ParagraphElementStatic } from '@/components/ui/paragraph-element-static';
import { HeadingElementStatic } from '@/components/ui/heading-element-static';
// For a styled static output, you might use a wrapper like EditorStatic
import { EditorStatic } from '@/components/ui/editor-static';
 
// Create a server-side editor instance
const editor = createSlateEditor({
  plugins: [
    BaseHeadingPlugin,   // Base plugin for headings
    // ... add all other base plugins relevant to your content
  ],
});
 
// Map plugin keys to their STATIC rendering components
const components = {
  p: ParagraphElementStatic, // 'p' is the default key for paragraphs
  h1: HeadingElementStatic,
  // ... add mappings for all your elements and marks
};
 
async function getMyHtml() {
  // Example: set some content on the server-side editor
  editor.children = [
    { type: 'h1', children: [{text: 'My Title'}] },
    { type: 'p', children: [{text: 'My content.'}] }
  ];
 
  const html = await serializeHtml(editor, {
    components,
    // Optional: Use a custom wrapper like EditorStatic for styling
    // editorComponent: EditorStatic,
    // props: { variant: 'none', className: 'p-4 m-4 border' },
  });
 
  return html;
}

Styling Serialized HTML

serializeHtml returns only the HTML for the editor content itself. If you use styled components (like EditorStatic or custom static components with specific classes), you must ensure the necessary CSS is available in the final context where the HTML will be displayed.

This often means wrapping the serialized HTML in a full HTML document that includes your stylesheets:

lib/generate-full-html-document.ts

// ... (previous setup from generate-html.ts)
 
async function getFullHtmlDocument() {
  const editorHtmlContent = await getMyHtml(); // From previous example
 
  const fullHtml = `<!DOCTYPE html>
  <html>
    <head>
      <meta charset="UTF-8">
      <meta name="viewport" content="width=device-width, initial-scale=1.0">
      <link rel="stylesheet" href="/path/to/your-global-styles.css" />
      <link rel="stylesheet" href="/path/to/tailwind-or-component-styles.css" />
      <title>Serialized Content</title>
    </head>
    <body>
      <div class="my-document-wrapper prose dark:prose-invert">
        ${editorHtmlContent}
      </div>
    </body>
  </html>`;
  return fullHtml;
}

Static Output Only

The serialization process converts Slate nodes to static HTML. Interactive features (React event handlers, client-side hooks) or components relying on browser APIs will not function in the serialized output.

Using Static Components

For server-side serialization, you must use static versions of your components (no client-only code, no React hooks like useEffect or useState).

Refer to the Static Rendering Guide for detailed instructions on creating server-safe static components for your Plate elements and marks.

components/ui/paragraph-element-static.tsx

import React from 'react';
import type { SlateElementProps } from '@udecode/plate';
 
// Example static paragraph component
export function ParagraphElementStatic(props: SlateElementProps) {
  return (
    <SlateElement {...props} className={cn('m-0 px-0 py-1')}>
      {props.children}
    </SlateElement>
  );
}

HTML to Plate

The HTML deserializer allows you to convert HTML content (strings or DOM elements) back into Plate format. This supports round-trip conversion, preserving structure, formatting, and attributes where corresponding plugin rules exist.

Basic Usage

Use editor.api.html.deserialize within a client-side Plate editor context.

components/my-html-importer.tsx

import { PlateEditor, usePlateEditor } from '@udecode/plate/react'; // React-specific imports for client-side
// Import ALL Plate plugins needed to represent the HTML content
import { HeadingPlugin } from '@udecode/plate-heading/react';
// ... and so on for bold, italic, tables, lists, etc.
 
function MyHtmlImporter({ htmlString }: { htmlString: string }) {
  const editor = usePlateEditor({
    plugins: [
      HeadingPlugin,     // For <h1>, <h2>, etc.
      // ... include all plugins corresponding to the HTML you expect to parse
    ],
  });
 
  const handleImport = () => {
    const slateValue = editor.api.html.deserialize(htmlString);
    editor.tf.setValue(slateValue);
  };
 
  // ... render your editor and a button to trigger handleImport ...
  return <button onClick={handleImport}>Import HTML</button>;
}

Client-Side Operation

HTML deserialization using editor.api.html.deserialize is typically a client-side operation as it interacts with a live Plate editor instance configured with React components and plugins.

Plugin Deserialization Rules Overview

Each Plate plugin can define rules for how it interprets specific HTML tags, styles, and attributes during deserialization. Below is a summary of common HTML structures and the Plate plugins typically responsible for them.

HTML Element / Style	Plate Plugin (Typical)	Notes
`<strong>`, `<b>`, `font-weight: 600,700,bold`	`BoldPlugin`	Converts to `bold: true` mark.
`<em>`, `<i>`, `font-style: italic`	`ItalicPlugin`	Converts to `italic: true` mark.
`<u>`, `text-decoration: underline`	`UnderlinePlugin`	Converts to `underline: true` mark.
`<s>`, `<del>`, `<strike>`, `text-decoration: line-through`	`StrikethroughPlugin`	Converts to `strikethrough: true` mark.
`<sub>`, `vertical-align: sub`	`SubscriptPlugin`	Converts to `subscript: true` mark.
`<sup>`, `vertical-align: super`	`SuperscriptPlugin`	Converts to `superscript: true` mark.
`<code>` (not in `<pre>`), `font-family: Consolas`	`CodePlugin`	Converts to `code: true` mark (inline code).
`<kbd>`	`KbdPlugin`	Converts to `kbd: true` mark.
`<p>`	`ParagraphPlugin`	Converts to paragraph element.
`<h1>` - `<h6>`	`HeadingPlugin`	Converts to corresponding heading elements (`h1` - `h6`).
`<ul>`	`ListPlugin`	Converts to unordered list (`ul` type). Items become `li`.
`<ol>`	`ListPlugin`	Converts to ordered list (`ol` type). Items become `li`.
`<li>` (within `<ul>` or `<ol>`)	`ListPlugin`	Converts to list item (`li` type), with `lic` (list item content) child.
`<li>` (with `aria-level` for indent)	`IndentListPlugin`	Converts to paragraph with `indent` and `listStyleType` props.
`<blockquote>`	`BlockquotePlugin`	Converts to blockquote element.
`<pre>` (often with `<code>` inside)	`CodeBlockPlugin`	Converts to `code_block` element. Content split into `code_line`.
`<hr>`	`HorizontalRulePlugin`	Converts to horizontal rule element.
`<a>`	`LinkPlugin`	Converts to link element (`a` type) with `url` property.
`<img>`	`ImagePlugin`	Converts to image element (`img` type) with `url` property.
`<iframe>`	`MediaEmbedPlugin`	Converts to media embed element, attempting to parse URL.
`<table>`	`TablePlugin`	Converts to `table` element.
`<tr>`	`TablePlugin`	Converts to `tr` (table row) element.
`<td>`	`TablePlugin`	Converts to `td` (table cell) element.
`<th>`	`TablePlugin`	Converts to `th` (table header cell) element.
`style="background-color: ..."`	`FontColorPlugin`	Converts to `backgroundColor` mark. (Plugin name might seem inverse)
`style="color: ..."`	`FontColorPlugin`	Converts to `color` mark.
`style="font-family: ..."`	`FontFamilyPlugin`	Converts to `fontFamily` mark.
`style="font-size: ..."`	`FontSizePlugin`	Converts to `fontSize` mark.
`style="font-weight: ..."` (other than bold values)	`FontWeightPlugin`	Converts to `fontWeight` mark for non-standard bold values.
`<mark>`	`HighlightPlugin`	Converts to `highlight: true` mark.
`style="text-align: ..."`	`AlignPlugin`	Sets `align` property on block elements.
`style="line-height: ..."`	`LineHeightPlugin`	Sets `lineHeight` property on block elements.

Plugin Configuration

The exact Plate type (e.g., ParagraphPlugin.key vs. 'p') depends on how plugins are configured. The table shows typical associations. Ensure the corresponding Plate plugins are included in your editor for these rules to apply.

Deserialization Properties in Plugins

Plugins can define how they handle HTML deserialization using properties within their parsers.html.deserializer configuration:

parse: A function ({ editor, element, getOptions, ... }) => Partial<SlateNode> that takes an HTML element and returns a partial Slate node. This is where the main conversion logic resides.
query: An optional function ({ element, getOptions }) => boolean that determines if the deserializer rule should even be considered for the current HTML element.
rules: An array of rule objects, each defining conditions for matching an HTML element:
- validNodeName: String or array of strings for matching HTML tag names (e.g., 'P', ['STRONG', 'B']).
- validAttribute: Object or array of objects specifying required attribute names and/or values (e.g., { align: ['left', 'center'] }).
- validClassName: String or array of strings for matching CSS class names.
- validStyle: Object or array of objects specifying required CSS style properties and/or values (e.g., { fontWeight: ['600', '700', 'bold'] }).
isElement: Boolean, true if the plugin deserializes an HTML element into a Slate Element node.
isLeaf: Boolean, true if the plugin deserializes an HTML element or style into a Slate Leaf (mark) on a Text node.
attributeNames: Array of HTML attribute names whose values should be preserved on the node.attributes property of the resulting Slate node.
withoutChildren: Boolean, if true, child nodes of the HTML element are not processed by convertHtmlAttributes.

Customizing Deserialization Behavior

You can extend a plugin to modify its HTML parsing logic. This is useful for supporting non-standard HTML attributes or structures.

lib/custom-code-block-plugin.ts

import { CodeBlockPlugin } from '@udecode/plate-code-block/react';
import { CodeLinePlugin } from '@udecode/plate-code-block'; // Base if needed
 
const MyCustomCodeBlockPlugin = CodeBlockPlugin.extend({
  parsers: {
    html: {
      deserializer: {
        // Inherit most rules and properties, then override or add
        ...CodeBlockPlugin.parsers.html.deserializer,
        parse: ({ element, editor }) => { // editor might be needed for getType
          const language = element.getAttribute('data-custom-lang') || element.className.match(/language-(?<lang>[^\s]+)/)?.groups?.lang;
          const textContent = element.textContent || '';
          const lines = textContent.split('\n');
 
          return {
            type: CodeBlockPlugin.key, // Or editor.getType(CodeBlockPlugin)
            lang: language,
            code: textContent, // Example: store full code string
            children: lines.map((line) => ({
              type: editor.getType(CodeLinePlugin), // Use editor.getType for safety
              children: [{ text: line }],
            })),
          };
        },
        rules: [
          // Inherit existing rules if desired
          ...(CodeBlockPlugin.parsers.html.deserializer.rules || []),
          // Add a new rule to match based on a custom attribute
          { validAttribute: { 'data-custom-lang': true } },
        ],
      },
    },
  },
});
 
// Then use MyCustomCodeBlockPlugin in your editor configuration.

This example customizes CodeBlockPlugin to look for a data-custom-lang attribute or a language-* class for determining the code language.

Advanced Deserialization Example (`IndentListPlugin`)

The IndentListPlugin demonstrates a more complex deserialization scenario where it transforms HTML list structures (<li> elements) into indented paragraphs within Plate, using aria-level to determine indentation.

Here's a conceptual look at its deserialization logic:

// Simplified concept from IndentListPlugin
export const IndentListPluginConfig = {
  // ... other configurations ...
  parsers: {
    html: {
      deserializer: {
        isElement: true,
        // query: ({ element }) => hasListAncestor(element), // Example condition
        parse: ({ editor, element }) => ({
          type: 'p', // Converts <li> to <p>
          indent: Number(element.getAttribute('aria-level') || '1'),
          listStyleType: element.style.listStyleType || undefined,
          // Children are processed by Plate's default deserializer after this node is created
        }),
        rules: [
          { validNodeName: 'LI' }, // Only applies to <li> elements
        ],
      },
    },
  },
};

This illustrates how a plugin can completely reinterpret HTML structures into a different Plate representation.

API Reference

`serializeHtml(editor, options)`

Converts Slate nodes from editor.children (or a provided value) into an HTML string. This function is typically used server-side.

Parameters

Collapse all

A server-side Plate editor instance, created via createSlateEditor.

Options for serialization.

OptionsSerializeHtmlOptions<P = PlateStaticProps>

Collapse all

A mapping of plugin keys (or node types) to their static React components for HTML rendering.

A React component to wrap the entire editor content during static rendering. Defaults to PlateStatic. The component receives editor, components, value, and any props passed here.

Props to pass to the editorComponent. P defaults to PlateStaticProps.

Slate nodes to serialize. If not provided, editor.children will be used.

An array of class name prefixes to preserve if stripClassNames is true. null preserves all if stripClassNames is true. Default: ['slate-', 'line-clamp'].

If true, removes all class names from the output HTML except those whose prefixes are listed in preserveClassNames. Default: true.

If true, removes all data-* attributes from the output HTML. Default: true.

Returns

Collapse all

A promise that resolves to the serialized HTML string.

`editor.api.html.deserialize(options)`

Parses an HTML string or HTMLElement into a Slate Value (an array of Descendant nodes). This is typically used on the client-side with a fully configured Plate editor.

Parameters

Collapse all

The client-side Plate editor instance.

Options for deserialization.

OptionsDeserializeHtmlOptions

Collapse all

The HTML string or HTMLElement to deserialize.

If true (default), collapses whitespace from text nodes similarly to how browsers treat whitespace in HTML. Set to false to preserve all whitespace. Default: true.

Deprecated. Use collapseWhiteSpace. If true, leading/trailing whitespace is trimmed and sequences of whitespace are collapsed. Default: true.

Returns

Collapse all

The deserialized Slate Value.

Next Steps

Explore the Static Rendering guide for creating server-safe components.
Review individual plugin documentation for specific HTML serialization/deserialization capabilities and default rules.
See the Server-Side HTML Generation Example.

Static Rendering Markdown

On This Page

Plate to HTML
HTML to Plate
API Reference
- serializeHtml(editor, options)
- editor.api.html.deserialize(options)
Next Steps

Build your editor

Production-ready AI template and reusable components.

HTML

Plate to HTML

Basic Usage

Styling Serialized HTML

Using Static Components

HTML to Plate

Basic Usage

Plugin Deserialization Rules Overview

Deserialization Properties in Plugins

Customizing Deserialization Behavior

Advanced Deserialization Example (`IndentListPlugin`)

API Reference

`serializeHtml(editor, options)`

Parameters

editor PlateEditor

options SerializeHtmlOptions

OptionsSerializeHtmlOptions<P = PlateStaticProps>

components Record<string, PlatePluginComponent>

editorComponent optional React.ComponentType<P>

props optional Partial<P>

value optional Descendant[]

preserveClassNames optional string[] | null

stripClassNames optional boolean

stripDataAttributes optional boolean

Returns

Promise<string>

`editor.api.html.deserialize(options)`

Parameters

editor PlateEditor

options DeserializeHtmlOptions

OptionsDeserializeHtmlOptions

element HTMLElement | string

collapseWhiteSpace optional boolean

stripWhitespace optional boolean

Returns

Descendant[]

Next Steps

HTML

Plate to HTML

Basic Usage

Styling Serialized HTML

Using Static Components

HTML to Plate

Basic Usage

Plugin Deserialization Rules Overview

Deserialization Properties in Plugins

Customizing Deserialization Behavior

Advanced Deserialization Example (IndentListPlugin)

API Reference

serializeHtml(editor, options)

Parameters

editor PlateEditor

editor PlateEditor

options SerializeHtmlOptions

options SerializeHtmlOptions

OptionsSerializeHtmlOptions<P = PlateStaticProps>

components Record<string, PlatePluginComponent>

components Record<string, PlatePluginComponent>

editorComponent optional React.ComponentType<P>

editorComponent optional React.ComponentType<P>

props optional Partial<P>

props optional Partial<P>

value optional Descendant[]

value optional Descendant[]

preserveClassNames optional string[] | null

preserveClassNames optional string[] | null

stripClassNames optional boolean

stripClassNames optional boolean

stripDataAttributes optional boolean

stripDataAttributes optional boolean

Returns

Promise<string>

Promise<string>

editor.api.html.deserialize(options)

Parameters

editor PlateEditor

editor PlateEditor

options DeserializeHtmlOptions

options DeserializeHtmlOptions

OptionsDeserializeHtmlOptions

element HTMLElement | string

element HTMLElement | string

collapseWhiteSpace optional boolean

collapseWhiteSpace optional boolean

stripWhitespace optional boolean

stripWhitespace optional boolean

Returns

Descendant[]

Descendant[]

Next Steps

Advanced Deserialization Example (`IndentListPlugin`)

`serializeHtml(editor, options)`

`editor.api.html.deserialize(options)`