Plate Core

API reference for @platejs/core.

API

createPlateEditor

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

OptionsCreatePlateEditorOptions

Collapse all

    Unique identifier for the editor.

    Initial editor without withPlate.

    An array of editor plugins.

    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)

    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

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

    Specifies the maximum number of characters allowed in the editor.

    Configuration for automatic node ID generation and management.

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

    Initial selection for the editor.

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

    • Default: false

    Function to configure the root plugin.

    API methods for the editor.

    Decoration function for the editor.

    Function to extend the editor.

    Event handlers for the editor.

    Injection configuration for the editor.

    Function to normalize the initial value.

    Additional options for the editor.

    Override configuration for the editor.

    Priority of the editor plugin.

    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.

createPlatePlugin

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

Parameters

Collapse all

    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

    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

    The base SlatePlugin to be extended.

    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

    The base SlatePlugin to be extended.

    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

    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.

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

    The plugin or plugin configuration with a required key.

ReturnsPlatePluginContext

Collapse all

    The current editor instance.

    The plugin instance.

    Function to get a specific option value.

    Function to get all options for the plugin.

    Function to set a specific option value.

    Function to set multiple options.

    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

    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

    The selector function.

    The dependency list for the selector function.

    Options for the selector function.

Options

Collapse all

    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

Collapse all

    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

    The ID of the plate editor.

Returnsboolean

    Whether the editor is composing.

useEditorReadOnly

Get the editor's readOnly state.

Parameters

Collapse all

    The ID of the plate editor.

Returnsboolean

    Whether the editor is read-only.

useEditorMounted

Get the editor's isMounted state.

Parameters

Collapse all

    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

    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

    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

    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

    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.

useNodePath

Returns the path of a node in the editor.

Parameters

Collapse all

    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

    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

    The plugin to get options from.

    The key of the option or selector to access.

    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

    The editor instance.

    The plugin to get options from.

    The key of the option or selector to access.

    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

    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

    The editor in which the node is present.

    The node to be checked.

    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

    The CSS class to apply to the component.

    The editor instance. Also available using useEditorRef 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

Collapse all

    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

Collapse all

    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'