Slate: Customizable Rich Text Editor Framework

Common errors

• Type 'MyCustomEditor' is not assignable to type 'ReactEditor'.
    Type 'MyCustomEditor' is missing the following properties from type 'ReactEditor': markIs) and related React DOM properties.

  cause Incorrectly extending Slate's built-in TypeScript types (Editor, Element, Text) or failing to declare the custom types module.
  fix Ensure you have a `declare module 'slate' { interface CustomTypes { Editor: MyCustomEditor; Element: MyCustomElement; Text: MyCustomText; } }` block in a `.d.ts` file or at the top of your relevant TypeScript file, and that your custom types correctly extend the base Slate types (`ReactEditor`, `BaseElement`, `BaseText`).

• Error: Editor instance not found in context. This is likely because you've used `useEditor` outside of a `<Slate>` context.

  cause Attempting to use `Editable` or any Slate-related hooks (`useEditor`, `useSlate`, etc.) outside of a `<Slate>` component context.
  fix Wrap your `Editable` component and any custom components utilizing Slate hooks within the `<Slate editor={editor} value={value} onChange={setValue}>` provider component.

• Cannot read properties of undefined (reading 'children') when rendering a custom element.

  cause Your `renderElement` or `renderLeaf` function is not correctly handling different types of nodes or is expecting properties that aren't present on the given node.
  fix Add a `default` case to your `switch` statement in `renderElement` and `renderLeaf` to handle unexpected node types gracefully. Ensure all custom element types you define in `CustomTypes` are explicitly handled in `renderElement`.

Warnings

• breaking Slate's `0.x` versioning scheme means that minor versions (`0.x.y` to `0.z.w` where `x != z`) can introduce significant breaking changes to the API and internal data structures. Users should always review the changelog when updating minor versions.
  Fix: Thoroughly review release notes for each minor version upgrade. Expect to refactor code related to editor operations, data models, or plugin APIs. Consult migration guides if available.
• gotcha The `slate@0.123.0` release introduced new, more efficient type discriminators like `Location.isPath`, `Location.isPoint`, `Location.isRange`, and `Location.isSpan`. While the older `Path.isPath`, `Point.isPoint`, etc., still exist, the new `Location` prefixed versions are recommended for better performance and consistency.
  Fix: Update existing code to use `Location.isPath`, `Location.isPoint`, `Location.isRange`, and `Location.isSpan` where appropriate, especially in performance-critical loops or frequently called functions.
• gotcha Ensuring the `Slate` component properly handles editor updates in `slate-react` requires careful management of the editor instance. If the `editor` object itself is re-created or mutated in a way that React's `useEffect` hooks don't track, the editor might not reflect changes correctly.
  Fix: Always initialize your editor instance using `useMemo` to ensure it's stable across renders, as shown in the quickstart. If your editor needs to dynamically change based on props, ensure `editor` is correctly listed as a dependency in relevant `useEffect` hooks, or pass an immutable editor instance.

Install

• npm install slate npm
• yarn add slate yarn
• pnpm add slate pnpm

Imports

• createEditor
  wrong:

  const createEditor = require('slate').createEditor;

  correct:

  import { createEditor } from 'slate';

  Primary function to initialize a new Slate editor instance. Modern usage strongly favors ESM imports.
• Slate, Editable, withReact
  wrong:

  const { Slate, Editable, withReact } = require('slate-react');

  correct:

  import { Slate, Editable, withReact } from 'slate-react';

  These are the core components and HOC for integrating Slate into a React application. `withReact` is essential for connecting the Slate editor to React's rendering lifecycle.
• Descendant, Editor, Element, Text

  import { Descendant, Editor, Element, Text } from 'slate';

  These are fundamental TypeScript types for defining the structure of Slate content and extending the editor's capabilities. Developers must extend these in their application's `CustomTypes`.
• withHistory

  import { withHistory } from 'slate-history';

  Used as an editor enhancer to add undo/redo capabilities.

Quickstart

This quickstart demonstrates how to set up a basic Slate editor with React and TypeScript, including custom type definitions and simple bold text rendering. It shows the initialization of the editor with `createEditor`, `withReact`, and `withHistory`, and then renders it using the `Slate` provider and `Editable` component.

import React, { useMemo, useState } from 'react';
import { createEditor, Descendant } from 'slate';
import { Slate, Editable, withReact, ReactEditor } from 'slate-react';
import { withHistory } from 'slate-history';

// Define our custom editor and element types for TypeScript to enable type safety
type CustomEditor = ReactEditor;
type ParagraphElement = { type: 'paragraph'; children: CustomText[] };
type CustomText = { text: string; bold?: boolean; italic?: boolean };

declare module 'slate' {
  interface CustomTypes {
    Editor: CustomEditor;
    Element: ParagraphElement;
    Text: CustomText;
  }
}

const initialValue: Descendant[] = [
  {
    type: 'paragraph',
    children: [{ text: 'Hello, Slate!' }],
  },
  {
    type: 'paragraph',
    children: [{ text: 'This is some ' }, { text: 'bold', bold: true }, { text: ' text.' }],
  },
];

const MySimpleEditor = () => {
  // Create a Slate editor object that won't change across renders.
  // It's enhanced with React capabilities and history (undo/redo).
  const editor = useMemo(() => withHistory(withReact(createEditor())), []);
  const [value, setValue] = useState<Descendant[]>(initialValue);

  return (
    <Slate editor={editor} value={value} onChange={setValue}>
      <Editable
        placeholder="Start typing..."
        // Define a rendering function for elements
        renderElement={props => <p {...props.attributes}>{props.children}</p>}
        // Define a rendering function for leaf nodes (text with formatting)
        renderLeaf={props => {
          let children = props.children;
          if (props.leaf.bold) children = <strong>{children}</strong>;
          if (props.leaf.italic) children = <em>{children}</em>;
          return <span {...props.attributes}>{children}</span>;
        }}
        style={{ border: '1px solid #ccc', padding: '10px', minHeight: '100px' }}
      />
    </Slate>
  );
};

export default MySimpleEditor;