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.

OptionsCreatePlateEditorOptions

  • id optional any

    Unique identifier for the editor.

  • editor optional E

    Initial editor without withPlate.

  • plugins optional P[]

    An array of editor plugins.

  • value optional V | string | ((editor: PlateEditor) => V | Promise<V>)

    Initial value of the editor. Can be:

    • A static value array
    • An HTML string to be deserialized
    • A function that returns a value (can be async)

  • autoSelect optional 'end' | 'start' | boolean

    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

  • onReady optional (ctx: { editor: PlateEditor; isAsync: boolean; value: V }) => void

    Callback called when the editor initialization completes. The isAsync flag indicates whether the value was loaded asynchronously.

  • maxLength optional number

    Specifies the maximum number of characters allowed in the editor.

  • nodeId optional object | boolean

    Configuration for automatic node ID generation and management.

  • chunking optional object | boolean

    Configure Slate's chunking optimization, which reduces latency while typing. Set to false to disable. Learn more about chunking.

  • selection optional TSelection

    Initial selection for the editor.

  • shouldNormalizeEditor optional boolean

    When true, it will normalize the initial value passed to the editor.

    • Default: false

  • rootPlugin optional (plugin: AnyPlatePlugin) => AnyPlatePlugin

    Function to configure the root plugin.

  • api optional object

    API methods for the editor.

  • decorate optional function

    Decoration function for the editor.

  • extendEditor optional function

    Function to extend the editor.

  • handlers optional object

    Event handlers for the editor.

  • inject optional object

    Injection configuration for the editor.

  • normalizeInitialValue optional function

    Function to normalize the initial value.

  • options optional object

    Additional options for the editor.

  • override optional object

    Override configuration for the editor.

  • priority optional number

    Priority of the editor plugin.

  • readOnly optional boolean

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

  • render optional object

    Render functions for the editor.

  • shortcuts optional object

    Keyboard shortcuts for the editor.

  • transforms optional object

    Transform functions for the editor.

  • useHooks optional function

    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.

createPlatePlugin

Creates a new Plate plugin with the given configuration, supporting extension, nested plugin manipulation, and runtime configuration.

Parameters

Collapse all

  • config PlatePluginConfig | ((editor: PlateEditor) => PlatePluginConfig)

    The configuration object for the plugin, or a function that returns the configuration. If a function is provided, it will be executed when the plugin is resolved with the editor.

    For details on the PlatePluginConfig type, refer to the PlatePlugin API.

ReturnsPlatePlugin

    A new plugin instance.

createTPlatePlugin

Explicitly typed version of createPlatePlugin.

Parameters

Collapse all

  • config TPlatePluginConfig<C> | ((editor: PlateEditor) => TPlatePluginConfig<C>)

    The configuration object for the plugin, or a function that returns the configuration. This version requires an explicit type parameter C extending AnyPluginConfig.

    For details on the TPlatePluginConfig type, refer to the PlatePlugin API.

ReturnsPlatePlugin<C>

    A new plugin instance.

toPlatePlugin

Extends a SlatePlugin to create a React PlatePlugin.

Parameters

Collapse all

  • basePlugin SlatePlugin

    The base SlatePlugin to be extended.

  • extendConfig optional PlatePluginConfig | ((ctx: PlatePluginContext<C>) => PlatePluginConfig)

    A function or object that provides the extension configuration. If a function, it receives the plugin context and should return a partial PlatePlugin. If an object, it should be a partial PlatePlugin configuration.

ReturnsPlatePlugin

    A new plugin instance that combines the base SlatePlugin functionality with React-specific features defined in the extension configuration.

toTPlatePlugin

Explicitly typed version of toPlatePlugin.

Parameters

Collapse all

  • basePlugin SlatePlugin<TContext>

    The base SlatePlugin to be extended.

  • extendConfig optional ExtendPluginConfig<C> | ((ctx: PlatePluginContext<TContext>) => ExtendPluginConfig<C>)

    A function or object that provides the extension configuration. This version requires explicit type parameters for both the base plugin configuration (TContext) and the extension configuration (C).

ReturnsPlatePlugin<C>

    A new plugin instance with precise type control.

usePlateEditor

Creates a memoized Plate editor for React components.

Parameters

Collapse all

  • options optional CreatePlateEditorOptions & { enabled?: boolean; onReady?: (ctx: { editor: PlateEditor; isAsync: boolean; value: V }) => void }

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

  • deps optional React.DependencyList

    Additional dependencies for the useMemo hook.

    • Default: []

ReturnsPlateEditor | null

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

useEditorContainerRef

ReturnsReact.RefObject<HTMLDivElement>

    The editor container DOM reference.

useEditorScrollRef

ReturnsReact.RefObject<HTMLDivElement>

    The editor scroll container DOM reference.

useScrollRef

ReturnsReact.RefObject<HTMLDivElement>

    The editor scroll container reference. Returns the scroll ref if it exists, otherwise returns the container ref.

useEditorPlugin

Get editor and plugin context.

Parameters

Collapse all

  • p WithRequiredKey<P>

    The plugin or plugin configuration with a required key.

ReturnsPlatePluginContext

Collapse all

  • editor PlateEditor

    The current editor instance.

  • plugin PlatePlugin

    The plugin instance.

  • getOption function

    Function to get a specific option value.

  • getOptions function

    Function to get all options for the plugin.

  • setOption function

    Function to set a specific option value.

  • setOptions function

    Function to set multiple options.

  • store PlateStore

    The Plate store for the editor.

useEditorRef

Get the Plate editor reference without re-rendering. The returned editor object is enhanced with a store property that provides access to the Plate store.

Parameters

Collapse all

  • id optional string

    Editor ID used for accessing nested editors. When not provided, returns the closest editor instance in the React tree. Only use this parameter when working with nested editors to target a specific scope.

ReturnsPlateEditor & { store: PlateStore }

    The editor reference with attached store.

useEditorSelector

Subscribe to a specific property of the editor.

Parameters

Collapse all

  • selector (editor: PlateEditor<V>, prev?: T) => T

    The selector function.

  • deps DependencyList

    The dependency list for the selector function.

  • options optional UseEditorSelectorOptions<T>

    Options for the selector function.

Options

Collapse all

  • id optional string

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

  • equalityFn optional (a: T, b: T) => boolean

    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

Collapse all

  • id optional string

    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

Collapse all

  • id optional string

    The ID of the plate editor.

Returnsboolean

    Whether the editor is composing.

useEditorReadOnly

Get the editor's readOnly state.

Parameters

Collapse all

  • id optional string

    The ID of the plate editor.

Returnsboolean

    Whether the editor is read-only.

useEditorMounted

Get the editor's isMounted state.

Parameters

Collapse all

  • id optional string

    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

Collapse all

  • id optional string

    The ID of the plate editor.

ReturnsTRange | null

    The current selection in the editor.

useEditorVersion

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

Parameters

Collapse all

  • id optional string

    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

Collapse all

  • id optional string

    The ID of the plate editor.

Returnsnumber

    The current version of the editor selection.

useSelectionCollapsed

Returnsboolean

    Whether the current selection is collapsed.

useSelectionExpanded

Returnsboolean

    Whether the current selection is expanded.

useSelectionWithinBlock

Returnsboolean

    Whether the current selection is within a single block.

useSelectionAcrossBlocks

Returnsboolean

    Whether the current selection spans across multiple blocks.

useSelectionFragment

Returns the fragment of the current selection, optionally unwrapping structural nodes.

ReturnsTElement[]

    The fragment of the current selection. Returns an empty array if the selection is not expanded or if no fragment is found.

useSelectionFragmentProp

Returns a prop value derived from the current selection fragment.

OptionsGetSelectionFragmentOptions & GetFragmentPropOptions

Collapse all

  • key optional string

    The key of the property to extract from each node.

  • defaultValue optional string

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

  • getProp optional (node: TElement | TText) => any

    Custom function to extract the prop value from a node.

  • mode optional 'all' | 'block' | 'text'

    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.

useNodePath

Returns the path of a node in the editor.

Parameters

Collapse all

  • node TNode

    The node to find the path for.

Returns

    A memoized Path array representing the location of the node in the editor's tree structure.

usePath

Get the memoized path of the closest element.

Parameters

Collapse all

  • pluginKey optional string

    The key of the plugin to get the path for.

Returns

    The path of the element, or undefined if used outside of a node component's context.

usePluginOption

Hook to access plugin options from the plugin store. For usage inside <Plate>.

Parameters

Collapse all

  • plugin PlatePlugin

    The plugin to get options from.

  • key keyof (InferOptions<C> | InferSelectors<C>) | 'state'

    The key of the option or selector to access.

  • ...args optional any[]

    Additional arguments:

    • For selectors: The selector parameters
    • Last argument can be an equality function (a: T, b: T) => boolean

ReturnsT

    The value of the option or selector result:

    • For 'state': Returns the entire state object
    • For selector keys: Returns the selector's return value
    • For option keys: Returns the option value
// Access a simple option
const value = usePluginOption(plugin, 'value');
// Access a selector with parameters
const doubleValue = usePluginOption(plugin, 'doubleValue', 2);
// Access with equality function
const value = usePluginOption(plugin, 'value', (a, b) => a === b);
// Access entire state
const state = usePluginOption(plugin, 'state');

useEditorPluginOption

Hook to access plugin options from the plugin store. For usage outside <Plate>.

Parameters

Collapse all

  • editor PlateEditor

    The editor instance.

  • plugin PlatePlugin

    The plugin to get options from.

  • key keyof (InferOptions<C> | InferSelectors<C>) | 'state'

    The key of the option or selector to access.

  • ...args optional any[]

    Additional arguments:

    • For selectors: The selector parameters
    • Last argument can be an equality function (a: T, b: T) => boolean

ReturnsT

    The value of the option or selector result:

    • For 'state': Returns the entire state object
    • For selector keys: Returns the selector's return value
    • For option keys: Returns the option value
// Access a simple option
const value = useEditorPluginOption(editor, plugin, 'value');
// Access a selector with parameters
const doubleValue = useEditorPluginOption(editor, plugin, 'doubleValue', 2);
// Access with equality function
const value = useEditorPluginOption(editor, plugin, 'value', (a, b) => a === b);
// Access entire state
const state = useEditorPluginOption(editor, plugin, 'state');

useElement

Get the element by plugin key.

Parameters

Collapse all

  • pluginKey optional string

    The key of the plugin to get the element for.

    • Default: 'element'

Returns

    The element of type T extends TElement, or an empty object if used outside of a node component's context.

Core plugins

DebugPlugin

Provides debugging capabilities with configurable log levels and error handling.

See Debugging for more details.

SlateExtensionPlugin & SlateReactExtensionPlugin

Extend core apis and improve default functionality.

DOMPlugin & ReactPlugin

Integrates React-specific functionality into the editor.

HistoryPlugin

Enables undo and redo functionality for the editor.

InlineVoidPlugin

Manages inline and void elements in the editor.

ParserPlugin

Handles parsing of content for the editor.

LengthPlugin

Enforces a maximum length for the editor content.

HtmlPlugin

Enables HTML serialization and deserialization.

AstPlugin

Handles Abstract Syntax Tree (AST) operations for the editor.

ParagraphPlugin

Provides paragraph formatting functionality.

EventEditorPlugin

Manages editor events such as focus and blur.

Utils

isType

Checks whether a node matches the provided type.

Parameters

Collapse all

  • editor PlateEditor<V>

    The editor in which the node is present.

  • node any

    The node to be checked.

  • key optional string | string[]

    The type or types to match the node against. Can be a string or an array of strings.

Returns

    A boolean indicating whether the node's type matches the provided type or types.

Components

<PlateElement>

Generic component for rendering an element.

Props

Collapse all

  • className optional string

    The CSS class to apply to the component.

  • editor E

    The editor instance. Also available using useEditorRef hook.

  • element TElement

    The element node. Also available using useElement hook.

  • path Path

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

  • attributes HTMLAttributes<HTMLElement>

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

  • children any

    Necessary for rendering the node children.

  • as optional React.ElementType

    The component type to render as.

    • Default: 'div'

<PlateLeaf>

Generic component for rendering a leaf.

Props

Collapse all

  • className optional string

    The CSS class to apply to the component.

  • editor E

    The editor context.

  • children any

    Necessary for rendering the node children.

  • leaf TText

    The leaf node.

  • text TText

    The text node.

  • attributes HTMLAttributes<HTMLElement>

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

  • as optional React.ElementType

    The component type to render as.

    • Default: 'span'

<PlateText>

Generic component for rendering text.

Props

Collapse all

  • className optional string

    The CSS class to apply to the component.

  • text TText

    The text node.

  • attributes HTMLAttributes<HTMLElement>

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

  • children any

    Necessary for rendering the node children.

  • as optional React.ElementType

    The component type to render as.

    • Default: 'span'
Plate 核心Floating