main
Walkthroughs
Concepts
Serializing
Slate's data model has been built with serialization in mind. Specifically, its text nodes are defined in a way that makes them easier to read at a glance, but also easy to serialize to common formats like HTML and Markdown.
And, because Slate uses plain JSON for its data, you can write serialization logic very easily.
Plaintext
For example, taking the value of an editor and returning plaintext:
1
import { Node } from 'slate'
2
​
3
const serialize = nodes => {
4
return nodes.map(n => Node.string(n)).join('\n')
5
}
Copied!
Here we're taking the children nodes of an
Editor as a nodes argument, and returning a plaintext representation where each top-level node is separated by a single \n new line character.For an input of:
1
const nodes = [
2
{
3
type: 'paragraph',
4
children: [{ text: 'An opening paragraph...' }],
5
},
6
{
7
type: 'quote',
8
children: [{ text: 'A wise quote.' }],
9
},
10
{
11
type: 'paragraph',
12
children: [{ text: 'A closing paragraph!' }],
13
},
14
]
Copied!
You'd end up with:
1
An opening paragraph...
2
A wise quote.
3
A closing paragraph!
Copied!
Notice how the quote block isn't distinguishable in any way, that's because we're talking about plaintext. But you can serialize the data to anything you want—it's just JSON after all.
HTML
For example, here's a similar
serialize function for HTML:1
import escapeHtml from 'escape-html'
2
import { Text } from 'slate'
3
​
4
const serialize = node => {
5
if (Text.isText(node)) {
6
let string = escapeHtml(node.text)
7
if (node.bold) {
8
string = `<strong>${string}</strong>`
9
}
10
return string
11
}
12
​
13
const children = node.children.map(n => serialize(n)).join('')
14
​
15
switch (node.type) {
16
case 'quote':
17
return `<blockquote><p>${children}</p></blockquote>`
18
case 'paragraph':
19
return `<p>${children}</p>`
20
case 'link':
21
return `<a href="${escapeHtml(node.url)}">${children}</a>`
22
default:
23
return children
24
}
25
}
Copied!
This one is a bit more aware than the plaintext serializer above. It's actually recursive so that it can keep iterating deeper through a node's children until it gets to the leaf text nodes. And for each node it receives, it converts it to an HTML string.
It also takes a single node as input instead of an array, so if you passed in an editor like:
1
const editor = {
2
children: [
3
{
4
type: 'paragraph',
5
children: [
6
{ text: 'An opening paragraph with a ' },
7
{
8
type: 'link',
9
url: 'https://example.com',
10
children: [{ text: 'link' }],
11
},
12
{ text: ' in it.' },
13
],
14
},
15
{
16
type: 'quote',
17
children: [{ text: 'A wise quote.' }],
18
},
19
{
20
type: 'paragraph',
21
children: [{ text: 'A closing paragraph!' }],
22
},
23
],
24
// `Editor` objects also have other properties that are omitted here...
25
}
Copied!
You'd receive back (line breaks added for legibility):
1
<p>An opening paragraph with a <a href="https://example.com">link</a> in it.</p>
2
<blockquote><p>A wise quote.</p></blockquote>
3
<p>A closing paragraph!</p>
Copied!
It's really that easy!
Deserializing
Another common use case in Slate is doing the reverse—deserializing. This is when you have some arbitrary input and want to convert it into a Slate-compatible JSON structure. For example, when someone pastes HTML into your editor and you want to ensure it gets parsed with the proper formatting for your editor.
Slate has a built-in helper for this: the
slate-hyperscript package.The most common way to use
slate-hyperscript is for writing JSX documents, for example when writing tests. You might use it like so:1
/** @jsx jsx */
2
import { jsx } from 'slate-hyperscript'
3
​
4
const input = (
5
<fragment>
6
<element type="paragraph">A line of text.</element>
7
</fragment>
8
)
Copied!
And the JSX feature of your compiler (Babel, TypeScript, etc.) would turn that
input variable into:1
const input = [
2
{
3
type: 'paragraph',
4
children: [{ text: 'A line of text.' }],
5
},
6
]
Copied!
This is great for test cases, or places where you want to be able to write a lot of Slate objects in a very readable form.
However! This doesn't help with deserialization.
But
slate-hyperscript isn't only for JSX. It's just a way to build trees of Slate content. Which happens to be exactly what you want to do when you're deserializing something like HTML.For example, here's a
deserialize function for HTML:1
import { jsx } from 'slate-hyperscript'
2
​
3
const deserialize = el => {
4
if (el.nodeType === 3) {
5
return el.textContent
6
} else if (el.nodeType !== 1) {
7
return null
8
}
9
​
10
let children = Array.from(el.childNodes).map(deserialize)
11
​
12
if (children.length === 0) {
13
children = [{ text: '' }]
14
}
15
​
16
switch (el.nodeName) {
17
case 'BODY':
18
return jsx('fragment', {}, children)
19
case 'BR':
20
return '\n'
21
case 'BLOCKQUOTE':
22
return jsx('element', { type: 'quote' }, children)
23
case 'P':
24
return jsx('element', { type: 'paragraph' }, children)
25
case 'A':
26
return jsx(
27
'element',
28
{ type: 'link', url: el.getAttribute('href') },
29
children
30
)
31
default:
32
return el.textContent
33
}
34
}
Copied!
It takes in an
el HTML element object and returns a Slate fragment. So if you have an HTML string, you can parse and deserialize it like so:1
const html = '...'
2
const document = new DOMParser().parseFromString(html, 'text/html')
3
deserialize(document.body)
Copied!
With this input:
1
<p>An opening paragraph with a <a href="https://example.com">link</a> in it.</p>
2
<blockquote><p>A wise quote.</p></blockquote>
3
<p>A closing paragraph!</p>
Copied!
You'd end up with this output:
1
const fragment = [
2
{
3
type: 'paragraph',
4
children: [
5
{ text: 'An opening paragraph with a ' },
6
{
7
type: 'link',
8
url: 'https://example.com',
9
children: [{ text: 'link' }],
10
},
11
{ text: ' in it.' },
12
],
13
},
14
{
15
type: 'quote',
16
children: [
17
{
18
type: 'paragraph',
19
children: [{ text: 'A wise quote.' }],
20
},
21
],
22
},
23
{
24
type: 'paragraph',
25
children: [{ text: 'A closing paragraph!' }],
26
},
27
]
Copied!
And just like the serializing function, you can extend it to fit your exact domain model's needs.
Last modified 9mo ago
Copy link