Plate.js Rich Text Editor Framework

Common errors

• Error: `editor` object is not defined in the context. Make sure you are rendering `Plate`.

  cause Attempting to use Plate hooks (e.g., `useEditorRef`, `usePlateEditor`) outside of a `<Plate>` component's render tree, or before the `editor` prop is passed to `<Plate>`.
  fix Ensure that any component using Plate-specific hooks is a child of a `<Plate>` component and that the `editor` prop is correctly provided to `<Plate>`.

• Cannot read properties of undefined (reading 'children')

  cause This is a common Slate error indicating that the editor's `value` (the document state) is malformed, specifically, a node is missing its `children` array or `text` property, or a block node is directly followed by a text node without an intervening inline node.
  fix Validate your `initialValue` and any programmatically inserted nodes against Slate's schema. Ensure all nodes have the correct structure: text nodes must have a `text` property, and element nodes must have a `children` array.

• Invariant Violation: Minified React error #XXX; visit https://reactjs.org/docs/error-decoder.html?invariant=XXX for the full message.

  cause Mismatch between React versions required by Plate.js (and its peer dependencies) and the React version installed in your project.
  fix Verify that your `react` and `react-dom` versions satisfy Plate.js's peer dependency requirements (e.g., `>=18.0.0` for recent Plate versions). Use `npm ls react` or `yarn why react` to inspect your dependency tree.

Warnings

• breaking Plate.js is built on Slate.js, which has a rapidly evolving API. Major version updates (e.g., Slate v0.50 to v0.60, or v0.80 to v0.90) often introduce significant breaking changes in Slate's core data model, API, and internal architecture. Plate.js generally follows Slate's versioning closely, meaning upgrades can require substantial code refactoring.
  Fix: Always consult the official Plate.js and Slate.js migration guides before upgrading major versions. Pin exact versions in `package.json` to prevent unexpected breaks.
• gotcha Performance can degrade significantly with very large documents or complex nested structures due to the nature of `contentEditable` and the extensive DOM manipulation required. Deeply nested components or custom renderers that re-render frequently can exacerbate this.
  Fix: Implement debouncing for onChange handlers, optimize custom renderers for memoization, virtualize long lists of elements, and consider splitting very large documents into smaller, manageable chunks.
• breaking Prior to Plate.js v15 (which aligned with Slate 0.90+), the plugin structure and editor initialization patterns differed significantly. Direct manipulation of the Slate editor object (`editor`) was more common, whereas newer versions emphasize a more declarative, plugin-driven approach.
  Fix: Migrate to the modern `createPlateEditor` and `plugins` array pattern. Review updated plugin options and hooks, as many legacy APIs have been removed or replaced. Consult the official migration guides for specific version jumps.
• gotcha Integrating custom plugins or complex features that heavily rely on direct Slate API interaction can be challenging. Plate.js aims to abstract Slate, but sometimes direct Slate knowledge is needed, potentially leading to conflicts with Plate's abstractions.
  Fix: When creating custom plugins, leverage Plate's `createPluginFactory` and the plugin lifecycle hooks. Access the underlying Slate editor instance via `editor.slate` when necessary, but prefer Plate's utility functions where available.

Install

• npm install platejs npm
• yarn add platejs yarn
• pnpm add platejs pnpm

Imports

• Plate
  wrong:

  import Plate from 'platejs'; // CommonJS default import is often wrong for modern libs

  correct:

  import { Plate } from '@platejs/react';

  The main Plate component is typically imported from `@platejs/react`, not the root `platejs` package directly.
• createPlateEditor
  wrong:

  import { createPlateEditor } from 'platejs';

  correct:

  import { createPlateEditor } from '@platejs/core';

  Core utilities for editor creation are found in `@platejs/core`.
• createParagraphPlugin
  wrong:

  import { createParagraphPlugin } from 'platejs/plugins';

  correct:

  import { createParagraphPlugin } from '@platejs/paragraph';

  Most plugins are imported from their own dedicated `@platejs/*` packages for better tree-shaking and modularity.
• useEditorRef
  wrong:

  import { useEditorRef } from '@platejs/core';

  correct:

  import { useEditorRef } from '@platejs/react';

  React-specific hooks like `useEditorRef` are part of `@platejs/react`.

Quickstart

This quickstart initializes a basic Plate.js editor with paragraph, basic elements, alignment, and basic mark plugins (bold, italic). It demonstrates the minimal setup for a functional editor component.

import React, { useMemo } from 'react';
import { createPlateEditor } from '@platejs/core';
import { Plate, usePlateEditorRef, PlateContent } from '@platejs/react';
import { createParagraphPlugin } from '@platejs/paragraph';
import { createBasicElementsPlugin } from '@platejs/elements';
import { createAlignPlugin } from '@platejs/alignment';
import { createBoldPlugin, createItalicPlugin } from '@platejs/basic-marks';

const initialValue = [
  { type: 'p', children: [{ text: 'Hello, Plate.js!' }] },
  { type: 'p', children: [{ text: 'Start typing here...' }] },
];

function MyEditor() {
  const plugins = useMemo(
    () => [
      createParagraphPlugin(),
      createBasicElementsPlugin(),
      createAlignPlugin({ options: { align: 'left' } }),
      createBoldPlugin(),
      createItalicPlugin(),
    ],
    []
  );

  const editor = useMemo(() => createPlateEditor(), []);

  return (
    <Plate editor={editor} plugins={plugins} initialValue={initialValue}>
      <PlateContent
        className="p-4 min-h-[200px] border border-gray-300 rounded-md"
        placeholder="Type something..."
      />
    </Plate>
  );
}

export default MyEditor;