0
# Slate React
1
2
Slate React provides React-specific integration components, hooks, and utilities for building completely customizable rich text editors using the Slate framework. It enables developers to create sophisticated rich text editing experiences similar to Medium, Google Docs, or Dropbox Paper while maintaining full control over styling, behavior, and functionality through React's component model.
3
4
## Package Information
5
6
- **Package Name**: slate-react
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install slate-react react react-dom slate slate-dom`
10
11
## Core Imports
12
13
```typescript
14
import {
15
Slate,
16
Editable,
17
withReact,
18
useSlate,
19
useSlateStatic,
20
ReactEditor,
21
RenderElementProps,
22
RenderLeafProps,
23
RenderTextProps,
24
RenderPlaceholderProps,
25
RenderChunkProps
26
} from "slate-react";
27
```
28
29
For CommonJS:
30
31
```javascript
32
const {
33
Slate,
34
Editable,
35
withReact,
36
useSlate,
37
useSlateStatic,
38
ReactEditor
39
} = require("slate-react");
40
```
41
42
## Basic Usage
43
44
```typescript
45
import React, { useMemo, useState } from 'react';
46
import { createEditor, Descendant } from 'slate';
47
import { Slate, Editable, withReact } from 'slate-react';
48
49
const MyEditor = () => {
50
const editor = useMemo(() => withReact(createEditor()), []);
51
const [value, setValue] = useState<Descendant[]>([
52
{
53
type: 'paragraph',
54
children: [{ text: 'A line of text in a paragraph.' }],
55
},
56
]);
57
58
return (
59
<Slate
60
editor={editor}
61
initialValue={value}
62
onChange={setValue}
63
>
64
<Editable
65
placeholder="Enter some rich text…"
66
renderElement={({ attributes, children, element }) => (
67
<div {...attributes}>{children}</div>
68
)}
69
renderLeaf={({ attributes, children, leaf }) => (
70
<span {...attributes}>{children}</span>
71
)}
72
/>
73
</Slate>
74
);
75
};
76
```
77
78
## Architecture
79
80
Slate React is built around several key components:
81
82
- **Provider Pattern**: `Slate` component manages editor state and provides context
83
- **Editable Component**: `Editable` handles DOM rendering, events, and user interactions
84
- **Plugin System**: `withReact()` enhances editors with React-specific behaviors
85
- **Hook System**: React hooks for accessing editor state, selection, and focus
86
- **Render Props**: Customizable render functions for elements, leaves, text, and placeholders
87
- **Performance Optimization**: Chunking system and selective re-rendering for large documents
88
89
## Capabilities
90
91
### Core Components
92
93
Essential React components for building rich text editors. The foundation for any Slate React implementation.
94
95
```typescript { .api }
96
function Slate(props: {
97
editor: ReactEditor;
98
initialValue: Descendant[];
99
children: React.ReactNode;
100
onChange?: (value: Descendant[]) => void;
101
onSelectionChange?: (selection: Selection) => void;
102
onValueChange?: (value: Descendant[]) => void;
103
}): JSX.Element;
104
105
function Editable(props: EditableProps): JSX.Element;
106
```
107
108
[Core Components](./core-components.md)
109
110
### React Hooks
111
112
React hooks for accessing editor state, selection, focus, and other editor properties. Essential for building interactive editor features.
113
114
```typescript { .api }
115
function useSlate(): Editor;
116
function useSlateStatic(): Editor;
117
function useFocused(): boolean;
118
function useSelected(): boolean;
119
function useReadOnly(): boolean;
120
function useComposing(): boolean;
121
function useSlateSelection(): BaseSelection;
122
```
123
124
[React Hooks](./react-hooks.md)
125
126
### Plugin System
127
128
React-specific plugin functionality that integrates Slate with React's lifecycle and event system.
129
130
```typescript { .api }
131
function withReact<T extends BaseEditor>(
132
editor: T,
133
clipboardFormatKey?: string
134
): T & ReactEditor;
135
136
interface ReactEditor extends DOMEditor {
137
getChunkSize(node: Ancestor): number | null;
138
}
139
```
140
141
[Plugin System](./plugin-system.md)
142
143
### Render Functions
144
145
Customizable render functions for controlling how editor content is displayed. Essential for creating custom editor UI.
146
147
```typescript { .api }
148
interface RenderElementProps {
149
children: any;
150
element: Element;
151
attributes: {
152
'data-slate-node': 'element';
153
'data-slate-inline'?: true;
154
'data-slate-void'?: true;
155
dir?: 'rtl';
156
ref: any;
157
};
158
}
159
160
interface RenderLeafProps {
161
children: any;
162
leaf: Text;
163
text: Text;
164
attributes: {
165
'data-slate-leaf': true;
166
ref: any;
167
};
168
leafPosition?: LeafPosition;
169
}
170
```
171
172
[Render Functions](./render-functions.md)
173
174
### Performance Optimization
175
176
Advanced hooks and utilities for optimizing editor performance, especially important for large documents.
177
178
```typescript { .api }
179
function useSlateSelector<T>(
180
selector: (editor: Editor) => T,
181
equalityFn?: (a: T | null, b: T) => boolean,
182
options?: SlateSelectorOptions
183
): T;
184
185
interface SlateSelectorOptions {
186
deferred?: boolean;
187
}
188
```
189
190
[Performance Optimization](./performance-optimization.md)
191
192
### Utilities
193
194
Additional utility functions and re-exported constants from slate-dom.
195
196
```typescript { .api }
197
function defaultScrollSelectionIntoView(
198
editor: ReactEditor,
199
domRange: DOMRange
200
): void;
201
202
// Re-exported from slate-dom
203
const NODE_TO_INDEX: WeakMap<Node, number>;
204
const NODE_TO_PARENT: WeakMap<Node, Node>;
205
```
206
207
## Types
208
209
Core type definitions used throughout the API:
210
211
```typescript { .api }
212
interface EditableProps extends React.TextareaHTMLAttributes<HTMLDivElement> {
213
decorate?: (entry: NodeEntry) => DecoratedRange[];
214
onDOMBeforeInput?: (event: InputEvent) => void;
215
placeholder?: string;
216
readOnly?: boolean;
217
renderElement?: (props: RenderElementProps) => JSX.Element;
218
renderChunk?: (props: RenderChunkProps) => JSX.Element;
219
renderLeaf?: (props: RenderLeafProps) => JSX.Element;
220
renderText?: (props: RenderTextProps) => JSX.Element;
221
renderPlaceholder?: (props: RenderPlaceholderProps) => JSX.Element;
222
scrollSelectionIntoView?: (editor: ReactEditor, domRange: DOMRange) => void;
223
as?: React.ElementType;
224
disableDefaultStyles?: boolean;
225
}
226
227
interface RenderChunkProps {
228
highest: boolean;
229
lowest: boolean;
230
children: any;
231
attributes: {
232
'data-slate-chunk': true;
233
ref: any;
234
};
235
}
236
237
interface RenderTextProps {
238
text: Text;
239
children: any;
240
attributes: {
241
'data-slate-node': 'text';
242
ref: any;
243
};
244
}
245
246
interface RenderPlaceholderProps {
247
children: any;
248
attributes: {
249
'data-slate-placeholder': boolean;
250
dir?: 'rtl';
251
contentEditable: boolean;
252
ref: React.RefCallback<any>;
253
style: React.CSSProperties;
254
};
255
}
256
```