main
Walkthroughs
Concepts
Interfaces
Slate works with pure JSON objects. All it requires is that those JSON objects conform to certain interfaces. For example, a text node in Slate must obey the
Text interface:1
interface Text {
2
text: string
3
}
Copied!
Which means it must have a
text property with a string of content.But any other custom properties are also allowed, and completely up to you. This lets you tailor your data to your specific domain and use case, adding whatever formatting logic you'd like, without Slate getting in the way.
This interface-based approach separates Slate from most other rich text editors which require you to work with their hand-rolled "model" classes and makes it much easier to reason about. It also means that it avoids startup time penalties related to "initializing" the data model.
Custom Properties
To take another example, the
Element node interface in Slate is:1
interface Element {
2
children: Node[]
3
}
Copied!
This is a very permissive interface. All it requires is that the
children property gets defined containing the element's child nodes.But you can extend elements (or any other interface) with your custom properties that are specific to your domain. For example, you might have "paragraph" and "link" elements:
1
const paragraph = {
2
type: 'paragraph',
3
children: [...],
4
}
5
​
6
const link = {
7
type: 'link',
8
url: 'https://example.com',
9
children: [...]
10
}
Copied!
The
type and url properties are your custom API. Slate sees that they exist, but doesn't use them. However, when Slate renders a link element, you'll receive an object with the custom properties attached so that you can render it as:1
<a href={element.url}>{element.children}</a>
Copied!
When getting started with Slate, it's important to understand all of the interfaces it defines. There are a handful of interfaces that are discussed in each of the guides.
Helper Functions
In addition to the typing information, each interface in Slate also exposes a series of helper functions that make them easier to work with.
For example, when working with nodes:
1
import { Node } from 'slate'
2
​
3
// Get the string content of an element node.
4
const string = Node.string(element)
5
​
6
// Get the node at a specific path inside a root node.
7
const descendant = Node.get(value, path)
Copied!
Or, when working with ranges:
1
import { Range } from 'slate'
2
​
3
// Get the start and end points of a range in order.
4
const [start, end] = Range.edges(range)
5
​
6
// Check if a range is collapsed to a single point.
7
if (Range.isCollapsed(range)) {
8
// ...
9
}
Copied!
There are many helper functions available for all common use cases when working with different interfaces. When getting started it helps to read through all of them so you can often simplify complex logic into just a handful of lines of code.
Custom Helpers
In addition to the built-in helper functions, you might want to define your custom helper functions and expose them on your custom namespaces.
For example, if your editor supports images, you might want a helper that determines if an element is an image element:
1
const isImageElement = element => {
2
return element.type === 'image' && typeof element.url === 'string'
3
}
Copied!
You can define these as one-off functions easily. But you might also bundle them up into namespaces, just like the core interfaces do, and use them instead.
For example:
1
import { Element } from 'slate'
2
​
3
// You can use `MyElement` everywhere to have access to your extensions.
4
export const MyElement = {
5
...Element,
6
isImageElement,
7
isParagraphElement,
8
isQuoteElement,
9
}
Copied!
This makes it easy to reuse domain-specific logic alongside the built-in Slate helpers.
Last modified 5mo ago
Copy link