(set: $shortTitle to "HTML -> Slate")\
(display: "Header")\
# Convert a HTML string to a Slate value
<pre>`deserializeHtml(editor, { element: '<!-- ... -->' })`</pre>\
[[How do I get the editor instance?|editor]](set: $shortTitle to "Find node")\
(display: "Header")\
# Find a specific node
How do you want to find a node?
- [[By its path|find-node-by-path]]
- [[By its type|find-node-by-type]]
- [[Containing the selection|find-node-above]]
- [[Using some arbitrary condition|find-node-by-condition]](set: $shortTitle to "Path for node")\
(display: "Header")\
# Find the path for a node
<pre>`findNodePath(editor, node) -> Path | undefined`</pre>\
[[How do I get the editor instance?|editor]](set: $shortTitle to "Get all nodes")\
(display: "Header")\
# Get all nodes in the editor
<pre>`getNodeEntries(editor, { at: [] }) -> Generator<[TNode, Path]>`</pre>\
(display: "generator")
[[How do I get the editor instance?|editor]](set: $shortTitle to "Get nodes matching a condition")\
(display: "Header")\
# Get all nodes matching a condition
<pre>```getNodeEntries(editor, {
match: { type: someType },
}) -> Generator<[TNode, Path]>```</pre>\
(display: "generator")
(display: "default-at")
[[How do I get the editor instance?|editor]](set: $shortTitle to "Slate -> HTML")\
(display: "Header")\
# Get the content of the editor as a HTML string
Caveats:
- Converting from a Slate value to HTML and back again is a lossy operation. Do not rely on HTML to store the authoritative copy of a Slate document.
- Plate's HTML serializer currently has a number of issues, many of which have workarounds. Please check the full docs and search GitHub and Discord for existing issues and discussions before creating a new one.
- Due to an intentional decision by the Vercel team, Next.js may have compatibility issues with Plate's HTML serializer. If you encounter an issue when using the HTML serializer in server-side Next.js code, please contact Vercel about this.
<pre>`serializeHtml(editor, { nodes: editor.children })`</pre>\
[[How do I get the editor instance?|editor]](set: $shortTitle to "Editor value")\
(display: "Header")\
# Get the current value of the editor
## Using the editor instance
The <code>children</code> property on the editor instance is mutated with the new value whenever the content of the editor changes.
<pre>editor.children -> Value</pre>\
[[How do I get the editor instance?|editor]]
## Using the onChange prop on Plate
The <code>onChange</code> prop is called whenever the content of the editor changes, and also when the selection changes.
<pre>```<Plate
// ...
onChange={(value) => /* ... */}
/>```</pre>\
## Using the handlers.onChange plugin option
The <code>onChange</code> handler is called whenever the content of the editor changes, and also when the selection changes.
<pre>```const myPlugin = createPluginFactory({
key: KEY_MY_PLUGIN,
handlers: {
onChange: (editor) => (value) => /* ... */,
},
});```</pre>\
To filter out selection changes, use <code>`editor.operations.some((op) => op.type !== 'set_selection')`</code>.
[[How do I create a custom plugin?]](set: $shortTitle to "Get node string")\
(display: "Header")\
# Get the text content of a node
<pre>`getNodeString(node) -> string`</pre>(if: $shortTitles does not match datamap)[(set: $shortTitles to (dm:))]\
(set: $shortTitles to it + (dm: (passage:)'s name, $shortTitle))\
(if: $breadcrumbs does not match array)[(set: $breadcrumbs to (a:))]\
(set: $breadcrumbs to it + (a:(passage:)'s name))\
(for: each _i, ...(range: 1, $breadcrumbs's length))[\
(set: _page to $breadcrumbs's (_i))\
(set: _title to _page of $shortTitles)\
(if: _i < $breadcrumbs's length)[\
(link: _title)[\
(if: _i is 1)[\
(set: $breadcrumbs to (a:))\
](else:)[\
(set: $breadcrumbs to (subarray: $breadcrumbs, 1, (_i - 1)))\
]\
(go-to: _page)\
] / \
](else:)[_title]\
](set: $shortTitle to "Custom plugins")\
(display: "Header")\
# How do I create a custom plugin?
Custom plugins can be created using <code>createPluginFactory</code>. The only required plugin option is <code>key</code>.
<pre>```const KEY_MY_PLUGIN = 'myPlugin';
const createMyPlugin = createPluginFactory({
key: KEY_MY_PLUGIN,
});
// ...
const plugins = createPlugins([
// ...
createMyPlugin(),
], {
components: {
// ...
},
});
<Plate
// ...
plugins={plugins}
/>
```</pre>(set: $shortTitle to "Insert node")\
(display: "Header")\
# Insert a node
<pre>```insertNodes(
editor,
nodeOrArrayOfNodes,
{
// Optional (default is current selection)
at: someLocation,
// Optional (default false)
nextBlock: true,
// Optional (default false)
removeEmpty: true,
}
)```</pre>\
If <code>nextBlock</code> is true, <code>insertNodes</code> will insert the node after the current block. By default, <code>insertNodes</code> will insert the node in the middle of the current block, splitting the block if necessary.
If <code>removeEmpty</code> is true and the current block is empty, <code>insertNodes</code> will remove the current block before replacing it with the new block.
[[How do I get the editor instance?|editor]](set: $shortTitle to "Home")\
(display: "Header")\
# Plate Interactive Docs
Welcome to the interactive docs tool for Plate. Use this tool to find the most idiomatic way of accomplishing common goals. For more information, see the full docs sites for (link-repeat: "Plate")[(open-url: 'https://platejs.org')] and (link-repeat: "Slate")[(open-url: 'https://docs.slatejs.org')].
To get started, click the link below that most closely matches your goal.
## Working with the editor content
- [[Get the current value of the editor]]
- [[Get the content of the editor as a HTML string]]
- [[Convert a HTML string to a Slate value]]
- [[Replace the value of the entire editor]]
## Querying nodes and paths
- [[Find a specific node]]
- [[Get all nodes matching a condition]]
- [[Get all nodes in the editor]]
- [[Find the path for a node]]
- [[Get the text content of a node]]
## Transforming nodes
- [[Insert a node]]
- [[Remove a node]]
- [[Replace the content of a node]]
- [[Set properties on a node]](set: $shortTitle to "Remove node")\
(display: "Header")\
# Remove a node
<pre>```removeNodes(editor, {
at: somePath,
})```</pre>\
[[How do I get the path for a node?|Find the path for a node]]
[[How do I get the editor instance?|editor]](set: $shortTitle to "Replace node children")\
(display: "Header")\
# Replace the content of a node
<pre>```replaceNodeChildren(editor, {
at: somePath,
nodes: someNewChildren,
})```</pre>\
[[How do I get the editor instance?|editor]](set: $shortTitle to "Replace editor value")\
(display: "Header")\
# Replace the value of the entire editor
<pre>```replaceNodeChildren(editor, {
at: [],
nodes: /* ... */,
})```</pre>\
If you also want to clear the undo history, call <code>resetEditor(editor)</code> before <code>replaceNodeChildren</code>.
[[How do I get the editor instance?|editor]](set: $shortTitle to "Set node")\
(display: "Header")\
# Set properties on a node
<pre>```setNodes(
editor,
someProps,
{
at: somePathOrRange,
}
)```</pre>\
This transform can be used to change the type of a node by setting its <code>type</code> property.
[[How do I get the editor instance?|editor]]By default, this searches only the current selection for matching nodes. To search the entire editor or a specific location instead, use the <code>at</code> option.
Use <code>`at: []`</code> to search the entire editor.(set: $shortTitle to "Get editor")\
(display: "Header")\
# Get the editor instance
Where are you trying to access the editor instance from?
- [[From inside a plugin|editor-from-plugin]]
- [[From a React component outside my editor|editor-from-outside]]
- [[From a React component inside my editor|editor-from-inside]]
- [[I need a temporary editor instance|temp-editor]](set: $shortTitle to "From within")\
(display: "Header")\
# Get the editor instance from inside
<pre>`useEditorRef() -> PlateEditor`</pre>\
This hook will return a mutable reference to the editor instance, but will not cause your React component to re-render. Usually, this is what you want. If you do want your React component to re-render when the editor content changes, use the <code>useEditorState</code> hook instead.
To re-render only when a value derived from the editor changes, you can use <code>useEditorSelector</code>.(set: $shortTitle to "From outside")\
(display: "Header")\
# Get the editor instance from outside
There are multiple ways of getting the editor instance from outside the Plate component.
## Pass in your own editor instance
You can create an editor instance yourself and pass it into the Plate component. When doing this, you should move the <code>plugins</code> prop from the Plate component to <code>createPlateEditor</code>.
<pre>```const [editor] = useState(() => createPlateEditor({
plugins: /* ... */,
});
return (
<Plate
editor={editor}
// Do NOT pass plugins={...}
// ...
>
{/* ... */}
</Plate>
);```</pre>\
## Using PlateController
Place a <code>`<PlateController>`</code> wrapper near the entry point of your React application. From anywhere inside PlateController, the <code>useEditorRef</code> hook will return the active editor, or a fallback editor if no active editor exists.
## Using the editorRef hook
<pre>```const editorRef = useRef<PlateEditor>(null);
return (
<Plate
editorRef={editorRef}
plugins={/* ... */}
// ...
>
{/* ... */}
</Plate>
);```</pre>(set: $shortTitle to "From plugin")\
(display: "Header")\
# Get the editor instance from inside a plugin
## From inside an event handler
<pre>```const createMyPlugin = createPluginFactory({
key: KEY_MY_PLUGIN,
handlers: {
onKeyDown: (editor) => (event) => /* ... */,
},
})```</pre>\
## Using the then option
The <code>then</code> plugin option lets you wrap other plugin options in a function that can access the editor.
<pre>```const createMyPlugin = createPluginFactory({
key: KEY_MY_PLUGIN,
then: (editor) => ({
/* other options here */
}),
})```</pre>(set: $shortTitle to "Containing the selection")\
(display: "Header")\
# Find a node containing the selection
<pre>```getAboveNode(editor, {
// Optionally specify a condition:
match: { type: someType },
}) -> [TNode, Path] | undefined```</pre>\
If you only want to match block elements, use <code>getBlockAbove</code> instead.
[[How do I get the editor instance?|editor]](set: $shortTitle to "By condition")\
(display: "Header")\
# Find a node by a condition
<pre>```findNode(editor, {
match: (node, path) => /* ... */,
}) -> [TNode, Path] | undefined```</pre>\
(display: "default-at")
[[How do I get the editor instance?|editor]](set: $shortTitle to "By path")\
(display: "Header")\
# Find a node by its path
<pre>`getNode(editor, path) -> TNode | null`</pre>\
[[How do I get the editor instance?|editor]](set: $shortTitle to "By type")\
(display: "Header")\
# Find a node by its type
<pre>```findNode(editor, {
match: { type: someType },
}) -> [TNode, Path] | undefined```</pre>\
(display: "default-at")
[[How do I get the editor instance?|editor]]You can iterate over a generator using <code>for...of</code>, or convert it to an array using <code>Array.from</code>.(set: $shortTitle to "Temporary editor")\
(display: "Header")\
# Create a temporary editor instance
Usually when working with Plate, you'll need the same editor instance that is used by the Plate component in order to do things like querying and transforming the editor content.
However, there may be times when any editor instance will work. In these cases, you can create a temporary editor instance.
<pre>```const editor = createPlateEditor({ plugins });```</pre><footer>These docs are a work in progress. (link-repeat: "Contribute to them here.")[(open-url: 'https://github.com/udecode/plate-interactive-docs')]</footer>