From zbeyens. The source code is available on GitHub.

Plate
PlatePliteEditorsTemplates
GitHub16kGitHub
DiscordDiscord
  • Plate
  • Plitev42
    • Editor API
    • Editor Transforms
    • Node
    • Element
    • Text
    • Path
    • Point
    • Range
    • Location
    • Location Ref
    • Document Change
  • Plate Core
    • Plate Components
    • Plate Editor
    • Plate Plugin
    • Plate Store
    • Plate Controller
  • Plate Utils
  • React Utils
  • cn
  • Floating
  • Resizable

Plate Core

PreviousNext

API reference for @platejs/core.

API

createPlateEditor

Generates a new instance of a PlateEditor, initialized with a set of plugins and their configurations.

Document ChangePlate Components

On This Page

APIcreatePlateEditorEditorApplicationSchemadefineDocumentMigrationsmigrateDocumentdefinePlatePlugintoPlatePluginusePlateEditoruseEditorRootElementuseEditorEditableElementuseEditorScrollElementuseEditorScrollElementRefuseEditorPluginuseEditoruseActiveEditoruseEditorSelectoruseEditorStateuseEditorComposinguseEditorReadOnlyuseEditorMounteduseEditorSelectionuseEditorVersionuseSelectionVersionuseSelectionFragmentPropusePathuseOptionalPathusePluginStoreuseEditorPluginStoreuseElementuseOptionalElementCore pluginsDebugPluginElementIdPluginElementStatePluginDOMPluginHistoryPluginInlineVoidPluginHtmlPluginParagraphPluginEventEditorPluginComponents<PlateElement><PlateLeaf><PlateText>
Build your editor
Production-ready AI template and reusable components.
Get all-access

OptionsCreatePlateEditorOptions

    Unique identifier for the editor.

    Initial editor without withPlate.

    An array of editor plugins.

    Synchronous initial document, persisted { document, schema } envelope, or primary-root array. Use the callback when decoding needs the compiled editor model. Load remote data before constructing the editor.

    Select the editor after initialization.

    • Default: false
    • true | 'end': Select the end of the editor
    • false: Do not select anything
    • 'start': Select the start of the editor

    Maximum character count for user-facing text, fragment, and node insertions.

    Application-owned target-version migration chain. Plate runs every required step before plugin document preparation and schema fitting.

    Configuration for the built-in navigation feedback plugin.

    Initial selection for the editor.

    Application schema policy and optional named lineage. Omit root for the standard paragraph root. A migration plan requires an exact id and version match.

    When true, it normalizes the initialValue passed to the editor.

    • Default: false

    API methods for the editor.

    Decoration function for the editor.

    Lifecycle and DOM events. Child names are prefixless, such as commit, nodeChange, keyDown, and paste.

    Injection configuration for the editor.

    Additional options for the editor.

    Override configuration for the editor.

    Editor read-only initial state. For dynamic value, use Plate.readOnly prop.

    Render functions for the editor.

    Keyboard shortcuts for the editor.

    Transform functions for the editor.

    Hook to use with the editor.

ReturnsPlateEditor

    An editor instance with plugins and config applied.

For more details on editor configuration, refer to the Editor Configuration guide.

EditorApplicationSchema

Defines application-owned schema policy. Its optional fields are:

  • root: primary-root SchemaContent with an explicit positive integer min. Descriptor sources must match the installed plugin family. The first source in schema.content.elements is the default.
  • overrides: final application overrides for installed element schemas and existing property targets.
  • properties: application-owned schema properties.
  • id and version: a paired persisted lineage. Supply both or neither.

Omitting root preserves Plate's standard minimum-one paragraph grammar. Root grammar participates in the compiled fingerprint and generated value contract.

defineDocumentMigrations

Defines one target-version migration chain for a named application schema. Each numeric key is the schema version produced by that step.

import { defineDocumentMigrations } from 'platejs/migrations';
 
import { fingerprint as v1Fingerprint } from './migrations/v2-add-section/from';
import { fingerprint as v2Fingerprint } from './migrations/v3-add-caption/from';
 
const migrations = defineDocumentMigrations(EditorSchema, {
  sourceFingerprints: {
    1: v1Fingerprint,
    2: v2Fingerprint,
  },
  steps: {
    2: migrateDocumentV2,
    3: migrateDocumentV3,
  },
  unversioned: 1,
});
import { defineDocumentMigrations } from 'platejs/migrations';
 
import { fingerprint as v1Fingerprint } from './migrations/v2-add-section/from';
import { fingerprint as v2Fingerprint } from './migrations/v3-add-caption/from';
 
const migrations = defineDocumentMigrations(EditorSchema, {
  sourceFingerprints: {
    1: v1Fingerprint,
    2: v2Fingerprint,
  },
  steps: {
    2: migrateDocumentV2,
    3: migrateDocumentV3,
  },
  unversioned: 1,
});

sourceFingerprints binds every supported historical envelope version to its generated schema fingerprint. unversioned assigns an explicit source version to raw documents without a persisted schema identity. Plate rejects missing intermediate steps and historical identity drift.

migrateDocument

Runs the required migration steps for one complete document without publishing it to the editor. Runtime editor loads and plate migrate run use this runner.

import { migrateDocument } from 'platejs/migrations';
 
const result = migrateDocument(persisted, {
  editor,
  migrations: EditorMigrations,
});
import { migrateDocument } from 'platejs/migrations';
 
const result = migrateDocument(persisted, {
  editor,
  migrations: EditorMigrations,
});

The result contains document, mapped selection, source, target, and the ascending applied version list. The runner rejects a different schema lineage, a future source, or fingerprint drift.

definePlatePlugin

Creates a React Plate plugin from one inferred definition.

Parameters

    The stable capability name used for plugin lookup and API namespaces.

    The plugin definition. The factory infers its name, initial state, API, read and update methods, schema, dependencies, native Plite capabilities, and React fields from this object.

ReturnsPlatePlugin

    A new plugin instance.

toPlatePlugin

Extends a BasePlugin to create a React PlatePlugin.

Parameters

    The base BasePlugin to be extended.

    React-specific fields to add to the exact Base plugin definition.

ReturnsPlatePlugin

    A new plugin descriptor that preserves the exact Base definition and adds the supplied React fields.

usePlateEditor

Creates a memoized Plate editor for React components.

Parameters

    Configuration options for creating the Plate editor. All options from createPlateEditor are supported, plus:

    Additional dependencies for the useMemo hook.

    • Default: []

ReturnsPlateEditor | null

    A memoized Plate editor instance. Returns null if enabled is false.

useEditorRootElement

ReturnsHTMLElement | null

    The mounted editor root element.

useEditorEditableElement

ReturnsHTMLElement | null

    The mounted editable element for the current Plite root.

useEditorScrollElement

ReturnsHTMLElement | null

    The element Plite uses as the editor scroll container.

useEditorScrollElementRef

Returns(element: HTMLElement | null) => void

    A callback ref that registers a custom editor scroll container.

useEditorPlugin

Get an installed plugin's flat consumer portal.

Parameters

    The plugin or plugin configuration with a required name.

ReturnsPlatePluginPortal

    The installed plugin name.

    The current plugin's mutable editor-local store.

useEditor

Get the active Plate editor without re-rendering. The hook throws when no matching editor is active.

Parameters

    Editor ID used for an explicit controller scope. Without an ID, the hook resolves the nearest editor, active controller editor, or first primary controller editor.

ReturnsPlateEditor

    The editor reference.

useActiveEditor

Use useActiveEditor({ id? }) when no active editor is a valid UI state. It returns the same editor value as useEditor(), or null while the controller has no matching active editor.

useEditorSelector

Subscribe to a specific property of the editor.

Parameters

    The selector function.

    Options for the selector function.

Options

    The ID of the plate editor. Useful only when nesting editors. Default is using the closest editor id.

    Equality function to determine whether the result of the selector function has changed. Default is (a, b) => a === b.

ReturnsT

    The return value of the selector function.

useEditorState

Get the Plate editor reference with re-rendering.

Parameters

    The ID of the plate editor. Default is using the closest editor id.

ReturnsPlateEditor

    The editor reference.

useEditorComposing

Get the editor's composing state.

Parameters

    The ID of the plate editor.

Returnsboolean

    Whether the editor is composing.

useEditorReadOnly

Get the editor's readOnly state.

Parameters

    The ID of the plate editor.

Returnsboolean

    Whether the editor is read-only.

useEditorMounted

Get the editor's isMounted state.

Parameters

    The ID of the plate editor.

Returnsboolean

    Whether the editor is mounted.

useEditorSelection

Get the editor's selection. Memoized so it does not re-render if the range is the same.

Parameters

    The ID of the plate editor.

ReturnsRange | null

    The current selection in the editor.

useEditorVersion

Get the version of the editor value. That version is incremented on each editor change.

Parameters

    The ID of the plate editor.

Returnsnumber

    The current version of the editor value.

useSelectionVersion

Get the version of the editor selection. That version is incremented on each selection change (the range being different).

Parameters

    The ID of the plate editor.

Returnsnumber

    The current version of the editor selection.

useSelectionFragmentProp

Returns a prop value derived from the current selection fragment.

OptionsGetSelectionFragmentOptions & GetFragmentPropOptions

    The key of the property to extract from each node.

    The default value to return if no valid prop is found.

    Custom function to extract the prop value from a node.

    Determines how to traverse the fragment:

    • 'all': Check both block and text nodes

    • 'block': Only check block nodes

    • 'text': Only check text nodes

    • Default: 'block'

Returns

    A value derived from the fragment nodes, or undefined if no consistent value is found across the specified nodes.

usePath

Get the live path of the closest element and throw when the matching provider is absent. Pass a plugin descriptor to select an owning element provider.

Parameters

    Plugin descriptor whose configured element provider should be used.

Returns

    The current element path.

useOptionalPath

Use useOptionalPath(Plugin) when the provider is intentionally optional. It returns null instead of manufacturing a path for an arbitrary node object.

usePluginStore

Subscribe to a plugin state field, named selector, or selector callback inside <Plate>.

Pass the plugin descriptor itself—not a { name } object. The descriptor carries the state fields, selector arguments, and return types, so no generic arguments are needed.

Parameters

    The plugin whose editor-local store should be observed.

    A state key, named selector key, or selector callback.

    Arguments for a named selector. Selector callbacks instead accept { id?, equalityFn? } as the final options object.

ReturnsT

    The selected field or derived value.
const value = usePluginStore(plugin, "value");
const doubleValue = usePluginStore(plugin, "doubleValue", 2);
const state = usePluginStore(plugin, (state) => state);
const pair = usePluginStore(
  plugin,
  (state) => [state.value, state.label] as const,
  { equalityFn: shallow }
);
const value = usePluginStore(plugin, "value");
const doubleValue = usePluginStore(plugin, "doubleValue", 2);
const state = usePluginStore(plugin, (state) => state);
const pair = usePluginStore(
  plugin,
  (state) => [state.value, state.label] as const,
  { equalityFn: shallow }
);

useEditorPluginStore

Explicit-editor variant of usePluginStore.

Parameters

    The editor instance.

    The plugin whose store should be observed.

    A state key, named selector key, or selector callback.

    Arguments for a named selector. Selector callbacks instead accept { equalityFn? } as the final options object.

ReturnsT

    The selected field or derived value.
const value = useEditorPluginStore(editor, plugin, "value");
const doubleValue = useEditorPluginStore(editor, plugin, "doubleValue", 2);
const state = useEditorPluginStore(editor, plugin, (state) => state);
const value = useEditorPluginStore(editor, plugin, "value");
const doubleValue = useEditorPluginStore(editor, plugin, "doubleValue", 2);
const state = useEditorPluginStore(editor, plugin, (state) => state);

useElement

Get the current element and throw when the matching provider is absent. Pass a plugin descriptor for configured schema inference. Call it without a descriptor only when deliberately working with the erased Element shape.

Parameters

    Plugin descriptor whose configured element provider and schema type should be inferred.

ReturnsPlateElementForDescriptor<TPlugin> | Element

    The current element. Throws when used outside the requested element provider.

import { BlockquotePlugin } from "@platejs/basic-nodes/react";
import { useElement } from "platejs/react";
 
const quote = useElement(BlockquotePlugin);
const generic = useElement();
import { BlockquotePlugin } from "@platejs/basic-nodes/react";
import { useElement } from "platejs/react";
 
const quote = useElement(BlockquotePlugin);
const generic = useElement();

useOptionalElement

Use useOptionalElement(Plugin) when a specific provider is optional, or call useOptionalElement() for the erased nearest provider. It returns null instead of a placeholder element.

Core plugins

DebugPlugin

Provides debugging capabilities with configurable log levels and error handling.

See Debugging for more details.

ElementIdPlugin

Adds persisted string IDs to every block and inline element. It is opt-in and never assigns IDs to text nodes.

import { ElementIdPlugin, schema, target } from 'platejs';
import { createPlateEditor } from 'platejs/react';
 
const editor = createPlateEditor({
  plugins: [ElementIdPlugin],
});
 
const elementId = editor.plugin(ElementIdPlugin);
const key = editor.key(element);
const id = elementId.read.id(key);
const entry = id ? elementId.read.entry(id) : undefined;
import { ElementIdPlugin, schema, target } from 'platejs';
import { createPlateEditor } from 'platejs/react';
 
const editor = createPlateEditor({
  plugins: [ElementIdPlugin],
});
 
const elementId = editor.plugin(ElementIdPlugin);
const key = editor.key(element);
const id = elementId.read.id(key);
const entry = id ? elementId.read.entry(id) : undefined;

Configure initialState.generateId to replace the default full-length nanoid() generator. Use migrateElementIds(value, options) for stored input that lacks IDs, contains legacy numeric IDs, or needs a legacy property canonicalized through sourceKey.

The application schema can narrow the plugin-owned id target. Document preparation generates and retains IDs only for elements that match the compiled target.

const editor = createPlateEditor({
  plugins: [ElementIdPlugin],
  schema: {
    overrides: [
      schema.override(ElementIdPlugin, {
        properties: { id: { target: target.group('block') } },
      }),
    ],
  },
});
const editor = createPlateEditor({
  plugins: [ElementIdPlugin],
  schema: {
    overrides: [
      schema.override(ElementIdPlugin, {
        properties: { id: { target: target.group('block') } },
      }),
    ],
  },
});

ElementStatePlugin

Extend Plate editor behavior on top of Plite.

ElementStatePlugin exposes editor.plugin(ElementStatePlugin).api.isEmpty(element). It checks the element's own props, not its text content. By default, only type and compiled element properties declared with role: "metadata" are ignored; any other prop means the element carries state. ElementIdPlugin declares its persisted ID property as metadata.

const elementState = editor.plugin(ElementStatePlugin);
 
elementState.api.isEmpty({
  children: [{ text: "" }],
  type: "paragraph",
}); // true
 
elementState.api.isEmpty({
  children: [{ text: "" }],
  listType: "bulleted",
  type: "paragraph",
}); // false
 
const CustomMetadataPlugin = defineBasePlugin("customMetadata", {
  schema: {
    properties: {
      customId: schema.elementProperty(property.string(), {
        role: "metadata",
        target: target.group("block"),
      }),
    },
  },
});
const elementState = editor.plugin(ElementStatePlugin);
 
elementState.api.isEmpty({
  children: [{ text: "" }],
  type: "paragraph",
}); // true
 
elementState.api.isEmpty({
  children: [{ text: "" }],
  listType: "bulleted",
  type: "paragraph",
}); // false
 
const CustomMetadataPlugin = defineBasePlugin("customMetadata", {
  schema: {
    properties: {
      customId: schema.elementProperty(property.string(), {
        role: "metadata",
        target: target.

DOMPlugin

Exposes DOM helpers for Plate and composes with Plite React on editable surfaces.

HistoryPlugin

Enables undo and redo functionality for the editor.

InlineVoidPlugin

Manages inline and void elements in the editor.

HtmlPlugin

Enables HTML serialization and deserialization.

ParagraphPlugin

Provides paragraph formatting functionality.

EventEditorPlugin

Manages editor events such as focus and blur.

Components

<PlateElement>

Generic component for rendering an element.

Props

    The CSS class to apply to the component.

    The editor instance. Also available using the strict useEditor hook.

    The element node. Also available using useElement hook.

    The path of the element in the editor tree. Also available using usePath hook.

    Attributes of the element to be spread on the top-level element.

    Necessary for rendering the node children.

    The component type to render as. - Default: 'div'

<PlateLeaf>

Generic component for rendering a leaf.

Props

    The CSS class to apply to the component.

    The editor context.

    Necessary for rendering the node children.

    The leaf node.

    The text node.

    Attributes of the leaf to be spread on the top-level element.

    The component type to render as. - Default: 'span'

<PlateText>

Generic component for rendering text.

Props

    The CSS class to apply to the component.

    The text node.

    Attributes of the text to be spread on the top-level element.

    Necessary for rendering the node children.

    The component type to render as. - Default: 'span'

group
(
"block"
),
}),
},
},
});