0
# Core Components
1

2
Essential React components for building rich text editors. These components form the foundation of any Slate React implementation.
3

4
## Capabilities
5

6
### Slate Provider Component
7

8
The `Slate` component is a React provider that wraps the editor and manages its state. It provides the editor context to all child components and handles editor state changes.
9

10
```typescript { .api }
11
/**
12
 * Provider component that wraps the editor and manages state
13
 * @param props - Slate component props
14
 * @returns JSX element providing editor context
15
 */
16
function Slate(props: {
17
  editor: ReactEditor;
18
  initialValue: Descendant[];
19
  children: React.ReactNode;
20
  onChange?: (value: Descendant[]) => void;
21
  onSelectionChange?: (selection: Selection) => void;
22
  onValueChange?: (value: Descendant[]) => void;
23
}): JSX.Element;
24
```
25

26
**Usage Example:**
27

28
```typescript
29
import React, { useMemo, useState } from 'react';
30
import { createEditor, Descendant } from 'slate';
31
import { Slate, withReact } from 'slate-react';
32

33
const MyEditor = () => {
34
  const editor = useMemo(() => withReact(createEditor()), []);
35
  const [value, setValue] = useState<Descendant[]>([
36
    { type: 'paragraph', children: [{ text: 'Hello world!' }] }
37
  ]);
38

39
  return (
40
    <Slate 
41
      editor={editor} 
42
      initialValue={value}
43
      onChange={setValue}
44
      onSelectionChange={(selection) => console.log('Selection changed:', selection)}
45
    >
46
      {/* Editor components go here */}
47
    </Slate>
48
  );
49
};
50
```
51

52
### Editable Component
53

54
The `Editable` component renders the main editor interface where users can input and edit text. It handles DOM events, keyboard interactions, and content rendering.
55

56
```typescript { .api }
57
/**
58
 * Main editable component that renders the editor content area
59
 * @param props - Editable component props
60
 * @returns JSX element for the editable area
61
 */
62
function Editable(props: EditableProps): JSX.Element;
63

64
interface EditableProps extends React.TextareaHTMLAttributes<HTMLDivElement> {
65
  /** Function to add decorations to text ranges */
66
  decorate?: (entry: NodeEntry) => DecoratedRange[];
67
  /** Handler for DOM beforeinput events */
68
  onDOMBeforeInput?: (event: InputEvent) => void;
69
  /** Placeholder text when editor is empty */
70
  placeholder?: string;
71
  /** Whether the editor is read-only */
72
  readOnly?: boolean;
73
  /** ARIA role for accessibility */
74
  role?: string;
75
  /** CSS styles for the editor */
76
  style?: React.CSSProperties;
77
  /** Custom element renderer */
78
  renderElement?: (props: RenderElementProps) => JSX.Element;
79
  /** Custom chunk renderer for performance optimization */
80
  renderChunk?: (props: RenderChunkProps) => JSX.Element;
81
  /** Custom leaf renderer */
82
  renderLeaf?: (props: RenderLeafProps) => JSX.Element;
83
  /** Custom text renderer */
84
  renderText?: (props: RenderTextProps) => JSX.Element;
85
  /** Custom placeholder renderer */
86
  renderPlaceholder?: (props: RenderPlaceholderProps) => JSX.Element;
87
  /** Custom scroll behavior for selection */
88
  scrollSelectionIntoView?: (editor: ReactEditor, domRange: DOMRange) => void;
89
  /** HTML element type to render (default: div) */
90
  as?: React.ElementType;
91
  /** Disable default Slate CSS styles */
92
  disableDefaultStyles?: boolean;
93
}
94
```
95

96
**Usage Example:**
97

98
```typescript
99
import React from 'react';
100
import { Editable, RenderElementProps, RenderLeafProps } from 'slate-react';
101

102
const renderElement = ({ attributes, children, element }: RenderElementProps) => {
103
  switch (element.type) {
104
    case 'paragraph':
105
      return <p {...attributes}>{children}</p>;
106
    case 'heading':
107
      return <h1 {...attributes}>{children}</h1>;
108
    default:
109
      return <div {...attributes}>{children}</div>;
110
  }
111
};
112

113
const renderLeaf = ({ attributes, children, leaf }: RenderLeafProps) => {
114
  if (leaf.bold) {
115
    children = <strong>{children}</strong>;
116
  }
117
  if (leaf.italic) {
118
    children = <em>{children}</em>;
119
  }
120
  return <span {...attributes}>{children}</span>;
121
};
122

123
const MyEditable = () => (
124
  <Editable
125
    placeholder="Type something..."
126
    renderElement={renderElement}
127
    renderLeaf={renderLeaf}
128
    onDOMBeforeInput={(event) => {
129
      // Handle input events
130
      console.log('Input event:', event);
131
    }}
132
  />
133
);
134
```
135

136
### Default Components
137

138
Slate React provides default components for common rendering scenarios. These can be used as-is or as references for custom implementations.
139

140
```typescript { .api }
141
/**
142
 * Default element renderer component
143
 * @param props - Element render props
144
 * @returns Default element rendering (span for inline, div for block)
145
 */
146
function DefaultElement(props: RenderElementProps): JSX.Element;
147

148
/**
149
 * Default leaf renderer component
150
 * @param props - Leaf render props
151
 * @returns Default leaf rendering (span)
152
 */
153
function DefaultLeaf(props: RenderLeafProps): JSX.Element;
154

155
/**
156
 * Default text renderer component
157
 * @param props - Text render props
158
 * @returns Default text rendering (span)
159
 */
160
function DefaultText(props: RenderTextProps): JSX.Element;
161

162
/**
163
 * Default placeholder renderer component
164
 * @param props - Placeholder render props
165
 * @returns Default placeholder rendering
166
 */
167
function DefaultPlaceholder(props: RenderPlaceholderProps): JSX.Element;
168
```
169

170
**Usage Example:**
171

172
```typescript
173
import { Editable, DefaultElement, DefaultLeaf } from 'slate-react';
174

175
// Use default components when you don't need custom rendering
176
const SimpleEditor = () => (
177
  <Editable
178
    renderElement={DefaultElement}
179
    renderLeaf={DefaultLeaf}
180
    placeholder="Start typing..."
181
  />
182
);
183
```
184

185
## Utility Functions
186

187
### Default Scroll Behavior
188

189
```typescript { .api }
190
/**
191
 * Default implementation to scroll DOM range into view
192
 * @param editor - The ReactEditor instance
193
 * @param domRange - DOM range to scroll into view
194
 */
195
function defaultScrollSelectionIntoView(
196
  editor: ReactEditor, 
197
  domRange: DOMRange
198
): void;
199
```
200

201
**Usage Example:**
202

203
```typescript
204
import { Editable, defaultScrollSelectionIntoView } from 'slate-react';
205

206
const CustomEditor = () => (
207
  <Editable
208
    scrollSelectionIntoView={defaultScrollSelectionIntoView}
209
    // or provide custom scroll behavior
210
    // scrollSelectionIntoView={(editor, domRange) => {
211
    //   // Custom scroll logic
212
    // }}
213
  />
214
);
215
```
216

217
## Component Integration
218

219
The core components work together to create a complete editing experience:
220

221
1. **Slate** provides the editor context and manages state
222
2. **Editable** handles user interactions and renders content
223
3. **Default components** provide fallback rendering behavior
224
4. **Custom render functions** allow complete control over appearance
225

226
```typescript
227
// Complete basic editor setup
228
import React, { useMemo, useState } from 'react';
229
import { createEditor, Descendant } from 'slate';
230
import { Slate, Editable, withReact } from 'slate-react';
231

232
const BasicEditor = () => {
233
  const editor = useMemo(() => withReact(createEditor()), []);
234
  const [value, setValue] = useState<Descendant[]>([
235
    { type: 'paragraph', children: [{ text: 'Hello world!' }] }
236
  ]);
237

238
  return (
239
    <Slate editor={editor} initialValue={value} onChange={setValue}>
240
      <Editable 
241
        placeholder="Enter text here..."
242
        renderElement={({ attributes, children }) => (
243
          <p {...attributes}>{children}</p>
244
        )}
245
        renderLeaf={({ attributes, children }) => (
246
          <span {...attributes}>{children}</span>
247
        )}
248
      />
249
    </Slate>
250
  );
251
};
252
```