Docs
PlatePlugin

PlatePlugin

API reference for Plate plugins.

Plate plugins are objects passed to Plate plugins prop.

Generic Types

The PlatePlugin interface uses four generic types:

Attributes

Collapse all

    Represents the plugin key. This type defines the literal string type for the plugin's unique identifier.

    Represents the plugin options. This type defines the structure of the options object that can be passed to the plugin.

    Represents the plugin API. This type defines the structure of any API functions the plugin may provide. These should not transform the editor state.

    Represents the plugin transforms. This type defines the structure of any editor transform functions the plugin may provide.

    Represents the plugin storage. This type defines the structure of any data the plugin may need to dynamically store.

Usage example:

type MyPluginOptions = { customOption: boolean };
type MyPluginTransforms = { customTransform: () => void };
type MyPluginQueries = { customQuery: () => boolean };
type MyPluginStorage = { customData: string };
 
const myPlugin = createPlugin<'myPlugin', MyPluginOptions, MyPluginTransforms, MyPluginQueries, MyPluginStorage>({
  key: 'myPlugin'
  // plugin implementation
});

Plugins Properties

Attributes

Collapse all

    Unique property used by Plate to store the plugins by key in editor.pluginsByKey.

    An object of API functions provided by the plugin.

    • An API function could be any utility that doesn't directly modify the editor state:
      • Synchronous or asynchronous functions
      • Query functions
      • Helper utilities
      • State accessors
    • API functions are stored in editor.api[key].
    • Can be accessed as editor.api.myPlugin.customFunction().
    • Useful for exposing plugin functionality to other plugins or external code.

    Example:

    const myPlugin = createPlugin({
  key: 'myPlugin',
  api: {
    getData: () => 'Some data',
  },
});
 
// Usage
const data = editor.api.myPlugin.getData();

    Transform functions provided by the plugin.

    • Transforms are functions that modify the editor state.
    • They are typically used for operations like:
      • Inserting, deleting, or modifying nodes
      • Applying or removing marks
      • Normalizing the document structure
    • Transforms are stored in editor.tf[key].
    • Can be accessed as editor.tf.myPlugin.customTransform().

    Example:

    const myPlugin = createPlugin({
  key: 'myPlugin',
  transforms: {
    insertNode: (text: string) => {
      editor.insertNode({ text });
    },
  },
});
 
// Usage
editor.transforms.myPlugin.insertNode('New text');

    Property used by Plate to render a slate element or leaf.

    • React component with element of leaf props.

    Property used by Plate to decorate editor ranges.

    type Decorate = (ctx: { editor: PlateEditor, plugin: PlatePlugin, entry: TNodeEntry }) => Range[] | undefined;

    Properties used by the HTML deserializer core plugin for each HTML element.

    Handlers called whenever the corresponding event occurs in the editor.

    • Handlers can also be passed as Plate props. These are called after the plugins handlers.
    • Event handlers can return a boolean flag to specify whether the event can be treated as being handled.
    • If it returns true, the next handlers will not be called.

    This attribute extends most textarea handlers like:

    • onCopy,
    • onPaste,
    • onFocus,
    • onBlur,
    • onDOMBeforeInput,
    • onKeyDown,
    • ...
    ({ event, editor, plugin }: { event: Event } & PlatePluginContext) => boolean | void;

    Property used by Plate to render nodes of this type as elements, i.e. renderElement.

    Property used by inlineVoid core plugin to set elements of this type as inline.

    Property used by Plate to render nodes of this type as leaves, i.e. renderLeaf.

    Property used by inlineVoid core plugin to set elements of this type as void.

    Property used by markableVoid core plugin to set void elements of this type as markable.

    Normalize value before passing it into the editor.

    Extended properties used by any plugin as options.

    • Its type is the second generic type of PlatePlugin.

    Property used by Plate to deeply override plugins by key.

    Recursive plugin support to allow having multiple plugins in a single plugin.

    • Plate eventually flattens all the plugins into the editor.

    Property used by Plate to override node component props.

    • If function, its returning value will be shallow merged to the old props, with the old props as parameter.
    • If object, its value will be shallow merged to the old props.
    object |
  ((props: PlateRenderElementProps & PlateRenderLeafProps) =>
    object | undefined);

    Render a component above Editable.

    Render a component above Slate.

    Render a component after Editable.

    Render a component before Editable.

    Property used by serializeHtml util to replace renderElement and renderLeaf when serializing a node of this type.

    React.FC<{
  className?: string;
  editor: PlateEditor;
  plugin: PlatePlugin;
  nodeProps?: AnyObject;
  children: any;
  attributes:
    | {
        'data-slate-node': 'element';
        'data-slate-inline'?: true;
        'data-slate-void'?: true;
        dir?: 'rtl';
        ref: any;
      }
    | {
        'data-slate-leaf': true;
      };
  element: TElement;
  leaf: TText;
  text: TText;
}>;

    Property used by Plate to render a node by type.

    • It requires slate element properties to have a type property with the plugin type as value.
    • Example: { type: 'p' } where plugin type is 'p'.
    • It requires slate leaf properties to have the plugin type value as key and true as value.
    • Example: { bold: true } where plugin type is 'bold'.
    • Default: is plugin key.

    Use any React hooks here. Each plugin useHooks will be called in a React component.

    (ctx: PlatePluginContext) => void;

    An array of plugin keys that this plugin depends on.

    • These plugins will be loaded before the current plugin.
    • Useful for ensuring that required plugins are available before the current plugin is initialized.
    • Example: ['indent']

    Editor method overriders.

    (ctx: PlatePluginContext) => void;

    Creates a new plugin instance with updated options.

    (options: Partial<O>) => PlatePlugin

    Creates a new plugin instance with additional configuration. Can accept either an object or a function.

    (extendConfig: Partial<PlatePlugin> | ((ctx: PlatePluginContext) => Partial<PlatePlugin>)) => PlatePlugin

    Extends an existing nested plugin or adds a new one if not found. Supports deep nesting.

    (key: string, extendConfig: Partial<PlatePlugin> | ((ctx: PlatePluginContext) => Partial<PlatePlugin>)) => PlatePlugin

Plugin Methods

  • configure: Creates a new plugin instance with updated options.
const configuredPlugin = myPlugin.configure({ someOption: false });

which is equivalent to

const configuredPlugin = myPlugin.extend({ options: { someOption: false } });
  • extend: Creates a new plugin instance with additional configuration. Can accept either an object or a function.
const extendedPlugin = myPlugin.extend({
  component: { anotherOption: false },
});
 
// or using a function
const functionallyExtendedPlugin = myPlugin.extend(({ editor, plugin }) => ({
  options: { editorOption: editor.someOption },
}));
  • extendPlugin: Extends an existing nested plugin or adds a new one if not found. Supports deep nesting.
const pluginWithNestedExtension = myPlugin.extendPlugin('nestedPlugin', {
  options: { nestedOption: true },
});
 
// Extending a deeply nested plugin
const deeplyExtendedPlugin = myPlugin.extendPlugin('deeplyNestedPlugin', {
  options: { deepOption: true },
});
 
// Using a function for dynamic extension
const dynamicallyExtendedPlugin = myPlugin.extendPlugin('dynamicPlugin', 
  ({ editor, plugin }) => ({
    options: { isActive: editor.selection !== null },
  })
);

Plugin Context

In most plugin functions, the first parameter extends PlatePluginContext. This object contains the following properties:

Attributes

Collapse all

    The editor instance.

    The plugin instance.

PlateEditorStore