Plugin Methods

Configuration Methods

When extending plugins, all properties are deeply merged by default, with two exceptions: arrays are replaced entirely, and the options object is shallow merged.

.configure

The .configure method allows you to override the plugin's configuration.

const ConfiguredPlugin = MyPlugin.configure({
  options: {
    myOption: 'new value',
  },
});

You can also use a function to access the current configuration:

const ConfiguredPlugin = MyPlugin.configure(({ getOptions }) => ({
  options: {
    ...getOptions(),
    myOption: `${getOptions().myOption} + extra`,
  },
}));

• It's used to modify existing properties of the plugin.
• It doesn't add new properties to the plugin.
• The last configuration applied is the one used by the editor.
• It doesn't return an extended type, maintaining the original plugin type.

.configurePlugin

The .configurePlugin method allows you to configure the properties of a nested plugin:

const TablePlugin = createPlatePlugin({
  key: 'table',
  plugins: [TableCellPlugin],
}).configurePlugin(TableCellPlugin, {
  options: {
    cellOption: 'modified',
  },
});

• It's used to configure nested plugins within a parent plugin.
• Like .configure, it modifies existing properties but doesn't add new ones.
• It's useful for adjusting the behavior of sub-plugins without extending their types.

.extend

The .extend method allows you to extend the plugin's configuration and functionality.

const ExtendedPlugin = MyPlugin.extend({
  options: {
    newOption: 'new value',
  },
});

You can also use a function to access the current configuration and editor:

const ExtendedPlugin = MyPlugin.extend(({ editor, plugin }) => ({
  options: {
    newOption: 'new value',
  },
  handlers: {
    onKeyDown: () => {
      // Custom key down logic
    },
  },
}));

• It's used to add new properties or modify existing ones in the plugin.
• It returns a new plugin instance with extended types.
• It's chainable, allowing multiple extensions to be applied sequentially.

.extendPlugin

The .extendPlugin method allows you to extend the configuration and functionality of a nested plugin:

const TablePlugin = createPlatePlugin({
  key: 'table',
  plugins: [TableCellPlugin],
}).extendPlugin(TableCellPlugin, {
  options: {
    newCellOption: 'added',
  },
  handlers: {
    onKeyDown: () => {
      // Custom key down logic for table cells
    },
  },
});

• It's used to extend nested plugins within a parent plugin.
• It can add new properties and modify existing ones in the nested plugin.
• It returns a new parent plugin instance with the extended nested plugin.

Difference between .configure and .extend

While both methods can be used to modify plugin configuration, they have some key differences:

1. Chaining: .extend is chainable, while .configure is not.
2. Type extension: .extend returns a new plugin instance with extended types, while .configure maintains the original type.
3. New properties: .extend can add new properties to the plugin configuration, while .configure only modifies existing ones.

Choose the appropriate method based on whether you need to extend the plugin's type and functionality (use .extend) or simply modify existing configuration (use .configure).

.extendSelectors

The extendSelectors method allows you to add subscribable selectors to your plugin:

const CounterPlugin = createPlatePlugin({
  key: 'counter',
  options: {
    count: 0,
  },
}).extendSelectors(({ getOptions }) => ({
  doubleCount: () => getOptions().count * 2,
  isEven: () => getOptions().count % 2 === 0,
}));

You can then use those selectors in your components or other plugin methods:

const CounterComponent = () => {
  const count = usePluginOption(CounterPlugin, 'count');
  const doubleCount = usePluginOption(CounterPlugin, 'doubleCount');
  const isEven = usePluginOption(CounterPlugin, 'isEven');

  return (
    <div>
      <p>Count: {count}</p>
      <p>Double Count: {doubleCount}</p>
      <p>Is Even: {isEven ? 'Yes' : 'No'}</p>
    </div>
  );
};

• It allows you to create derived state or computed values from plugin options.
• Read the value using getOption
• Subscribe to the value using usePluginOption, recomputed whenever options change, re-rendering only when the result changes. This is the main difference with .extendApi.

.withComponent

The withComponent method allows you to set or replace the component associated with a plugin.

const ParagraphPlugin = createPlatePlugin({
  key: 'p',
  node: {
    isElement: true,
    type: 'p',
  },
}).withComponent(ParagraphElement);

API and Transforms

Plugins can define their own API methods and transforms that will be merged into the editor's API and transforms. This is done using the extendApi, extendEditorApi, extendTransforms, and extendEditorTransforms methods.

.extendApi

Use extendApi to add plugin-specific API methods:

const MyPlugin = createPlatePlugin({
  key: 'myPlugin',
}).extendApi(() => ({
  pluginMethod: () => 'plugin method result',
}));

// Access the plugin's API
editor.api.myPlugin.api.pluginMethod();

.extendEditorApi

Use extendEditorApi to add root-level API methods:

const MyPlugin = createPlatePlugin({
  key: 'myPlugin',
}).extendEditorApi(({ getOptions }) => ({
  editorMethod: () => getOptions().someOption,
}));

// Access the plugin's API
editor.api.editorMethod();

.extendTransforms

Use extendTransforms to add plugin-specific transform methods:

const MyPlugin = createPlatePlugin({
  key: 'myPlugin',
}).extendTransforms(() => ({
  pluginTransform: () => {
    // Custom transform logic
  },
}));

// Access the plugin's transform
editor.tf.myPlugin.pluginTransform();

// NOTE: `editor.tf` in a short alias to `editor.transforms`
editor.transforms.myPlugin.pluginTransform();

.extendEditorTransforms

Use extendEditorTransforms to add root-level transform methods:

const MyPlugin = createPlatePlugin({
  key: 'myPlugin',
}).extendEditorTransforms(({ editor }) => ({
  editorTransform: () => {
    // Custom editor transform logic
  },
}));

// Access the plugin's transform
editor.tf.editorTransform();

.overrideEditor

The overrideEditor method is used specifically for overriding existing editor methods without altering the plugin's type:

const MyPlugin = createPlatePlugin({
  key: 'myPlugin',
}).overrideEditor(({ editor, tf: { insertText }, api: { isInline } }) => ({
  transforms: {
    insertText(text, options) {
      // Override insertText behavior
      insertText(text, options);
    },
  },
  api: {
    isInline(element) {
      // Override isInline behavior
      return isInline(element);
    },
  },
}));

• Used specifically for overriding existing editor methods
• Returns the overridden methods wrapped in transforms or api objects
• Cannot add new methods (use extendEditorTransforms or extendEditorApi instead)
• Provides access to original methods through the context

Difference between API and Transforms

While there is currently no core difference between API and Transforms in Plate, they serve distinct purposes and are designed with future extensibility in mind:

• Transforms:

  • Store all Slate transforms and editor operations here. Structured to potentially support middlewares in the future, allowing for more complex transform pipelines and devtools.
  • Typically used for operations that modify the editor state, such as inserting, deleting, or transforming content.
  • Example: editor.tf.toggleBlock(), editor.tf.toggleMark('bold')

• API:

  • Store all queries, utility functions, and other methods that don't directly modify the editor state.
  • Example: editor.api.save(), editor.api.debug.log()

Chaining Extensions

You can chain these methods to create a comprehensive plugin:

const MyPlugin = createPlatePlugin({
  key: 'myPlugin',
  options: {
    baseValue: 5,
  },
})
  .extendApi(() => ({
    pluginMethod: () => 'plugin method',
  }))
  .extendEditorApi(({ getOptions }) => ({
    multiply: (factor: number) => getOptions().baseValue * factor,
  }))
  .extendTransforms(() => ({
    pluginTransform: () => {
      // Plugin-specific transform
    },
  }))
  .extendEditorTransforms(({ editor }) => ({
    editorTransform: () => {
      // Editor-specific transform
    },
  }));

editor.api.myPlugin.api.pluginMethod();
editor.api.multiply(3);
editor.tf.myPlugin.pluginTransform();
editor.tf.editorTransform();

Convert a Slate Plugin to a Plate Plugin

To convert a typed Slate plugin to a Plate plugin, you can use toPlatePlugin:

const CodeBlockPlugin = toPlatePlugin(createSlatePlugin({ key: 'code_block' }), {
  handlers: {},
  options: { hotkey: ['mod+opt+8', 'mod+shift+8'] },
});