Editing Behavior

Editing behavior is the path from a key press or transform to the final document shape. Use Plugin Rules for declarative node policy, and use Editor Methods when you need an imperative transform. This guide shows how break, delete, merge, normalize, and selection behavior fit together.

On This Page

• Choose the Right Surface
• Runtime Pipeline
• Break Behavior
• Delete Behavior
• Merge Behavior
• Normalize Behavior
• Selection Behavior
• Recipes
• API Reference

Choose the Right Surface

Most editing behavior belongs in plugin.rules. Reach for custom transforms only when the rule table cannot express the behavior.

Rules keep common editor policy close to the plugin that owns the node. Transforms are still the right tool for commands, toolbar actions, and behavior that depends on app state.

Runtime Pipeline

Plate resolves plugins first, then core plugins wrap Slate APIs and transforms.

The normal flow is:

key press or command
  -> optional input rule for typed patterns
  -> plugin rule lookup for the current node
  -> editor.tf transform
  -> merge guard when nodes are joined
  -> normalization
  -> selection affinity cleanupCopy

key press or command
  -> optional input rule for typed patterns
  -> plugin rule lookup for the current node
  -> editor.tf transform
  -> merge guard when nodes are joined
  -> normalization
  -> selection affinity cleanupCopy

Input rules are for text patterns such as markdown shortcuts and autolinks. Plugin rules are for node behavior such as "a heading resets to paragraph on Backspace" or "a callout inserts soft breaks on Enter."

Break Behavior

rules.break controls editor.tf.insertBreak(), which is what Enter calls.

Plate checks the current block and handles these cases in order:

Use splitReset for blocks that should not keep their type after a normal split.

import { H1Plugin } from '@platejs/basic-nodes/react';
 
export const AppH1Plugin = H1Plugin.configure({
  rules: {
    break: {
      splitReset: true,
    },
  },
});Copy

import { H1Plugin } from '@platejs/basic-nodes/react';
 
export const AppH1Plugin = H1Plugin.configure({
  rules: {
    break: {
      splitReset: true,
    },
  },
});Copy

Use lineBreak and deleteExit for container-like blocks that need soft lines before they leave the block.

import { CalloutPlugin } from '@platejs/callout/react';
 
export const AppCalloutPlugin = CalloutPlugin.configure({
  rules: {
    break: {
      default: 'lineBreak',
      empty: 'reset',
      emptyLineEnd: 'deleteExit',
    },
  },
});Copy

import { CalloutPlugin } from '@platejs/callout/react';
 
export const AppCalloutPlugin = CalloutPlugin.configure({
  rules: {
    break: {
      default: 'lineBreak',
      empty: 'reset',
      emptyLineEnd: 'deleteExit',
    },
  },
});Copy

That callout keeps normal Enter inside the callout, resets empty callouts to paragraphs, and exits after a trailing empty line.

Delete Behavior

rules.delete controls collapsed Backspace behavior. Expanded selections still delete through the normal fragment path unless the whole editor is selected.

Plate checks collapsed deleteBackward in this order:

Use start: 'reset' for formatted text blocks that should become paragraphs before they merge into the previous block.

import { H1Plugin } from '@platejs/basic-nodes/react';
 
export const AppH1Plugin = H1Plugin.configure({
  rules: {
    delete: {
      start: 'reset',
    },
  },
});Copy

import { H1Plugin } from '@platejs/basic-nodes/react';
 
export const AppH1Plugin = H1Plugin.configure({
  rules: {
    delete: {
      start: 'reset',
    },
  },
});Copy

Use start: 'lift' for nested blocks that should move out one ancestor level.

import { createPlatePlugin } from 'platejs/react';
 
export const QuoteItemPlugin = createPlatePlugin({
  key: 'quote_item',
  node: {
    isElement: true,
  },
  rules: {
    delete: {
      start: 'lift',
    },
  },
});Copy

import { createPlatePlugin } from 'platejs/react';
 
export const QuoteItemPlugin = createPlatePlugin({
  key: 'quote_item',
  node: {
    isElement: true,
  },
  rules: {
    delete: {
      start: 'lift',
    },
  },
});Copy

When a selection spans multiple blocks, Plate deletes the selected content and then calls editor.tf.mergeNodes() at the end boundary. That means cross-block deletion can still enter the merge pipeline below.

Merge Behavior

Merge behavior decides whether two nodes can join and whether empty nodes at the boundary disappear.

editor.tf.mergeNodes() calls editor.api.shouldMergeNodes(prev, next, options) before it applies the merge. Plate's merge rules add three important guards:

Use removeEmpty: true for text-like blocks such as paragraphs and headings.

import { H1Plugin } from '@platejs/basic-nodes/react';
 
export const AppH1Plugin = H1Plugin.configure({
  rules: {
    merge: {
      removeEmpty: true,
    },
  },
});Copy

import { H1Plugin } from '@platejs/basic-nodes/react';
 
export const AppH1Plugin = H1Plugin.configure({
  rules: {
    merge: {
      removeEmpty: true,
    },
  },
});Copy

Keep removeEmpty: false for structural nodes that own layout, children, or wrappers. Tables, rows, cells, columns, and callouts should not disappear just because a merge crosses their boundary.

import { CalloutPlugin } from '@platejs/callout/react';
 
export const StableCalloutPlugin = CalloutPlugin.configure({
  rules: {
    merge: {
      removeEmpty: false,
    },
  },
});Copy

import { CalloutPlugin } from '@platejs/callout/react';
 
export const StableCalloutPlugin = CalloutPlugin.configure({
  rules: {
    merge: {
      removeEmpty: false,
    },
  },
});Copy

Normalize Behavior

rules.normalize runs during Slate normalization.

Use normalize.removeEmpty for elements that should not exist without text content. Links use this shape because an empty link has no useful editing surface.

import { LinkPlugin } from '@platejs/link/react';
 
export const AppLinkPlugin = LinkPlugin.configure({
  rules: {
    normalize: {
      removeEmpty: true,
    },
  },
});Copy

import { LinkPlugin } from '@platejs/link/react';
 
export const AppLinkPlugin = LinkPlugin.configure({
  rules: {
    normalize: {
      removeEmpty: true,
    },
  },
});Copy

Keep normalization rules boring. If a node needs a rich repair strategy, write a dedicated normalizer with .overrideEditor() so the behavior is explicit and testable.

Selection Behavior

rules.selection controls how marks and inline-like boundaries behave while typing, deleting, and moving the cursor.

Node flags also affect editing behavior. node.isInline, node.isVoid, node.isSelectable, and node.isMarkableVoid are resolved by the core override layer before selection and transform logic runs.

Recipes

For list metadata and code-block children, use rules.match so the feature plugin can apply its rule to the child block that actually contains the selection.

API Reference

Done. Rules describe the policy; transforms do the work.