Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Plate
✓ import { Plate } from '@platejs/react';
✗ import Plate from 'platejs'; // CommonJS default import is often wrong for modern libs
The main Plate component is typically imported from `@platejs/react`, not the root `platejs` package directly.
createPlateEditor
✓ import { createPlateEditor } from '@platejs/core';
✗ import { createPlateEditor } from 'platejs';
Core utilities for editor creation are found in `@platejs/core`.
createParagraphPlugin
✓ import { createParagraphPlugin } from '@platejs/paragraph';
✗ import { createParagraphPlugin } from 'platejs/plugins';
Most plugins are imported from their own dedicated `@platejs/*` packages for better tree-shaking and modularity.
useEditorRef
✓ import { useEditorRef } from '@platejs/react';
✗ import { useEditorRef } from '@platejs/core';
React-specific hooks like `useEditorRef` are part of `@platejs/react`.
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;
Debug
Known issues
breakingPlate.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.fixAlways consult the official Plate.js and Slate.js migration guides before upgrading major versions. Pin exact versions in `package.json` to prevent unexpected breaks.
affects: >=1.0.0 (any major version upgrade)
gotchaPerformance 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.fixImplement debouncing for onChange handlers, optimize custom renderers for memoization, virtualize long lists of elements, and consider splitting very large documents into smaller, manageable chunks.
affects: >=1.0.0
breakingPrior 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.fixMigrate 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.
affects: <15.0.0
gotchaIntegrating 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.fixWhen 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.
affects: >=1.0.0
Errors
Common errors & fixes
Error: `editor` object is not defined in the context. Make sure you are rendering `Plate`.
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>`.
fixEnsure 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')
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.
fixValidate 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.
Mismatch between React versions required by Plate.js (and its peer dependencies) and the React version installed in your project.
fixVerify 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.
Audit
Dependencies
reactrequiredRequired for rendering the editor UI and managing component state.
react-domrequiredRequired for rendering the React components to the DOM.