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
```