Editing behavior is the path from user intent to committed Plite state. Use this page for the runtime pipeline; use Selection And DOM for caret, native selection, and DOM coverage rules.
Most editing bugs come from putting behavior in the wrong layer.
| Surface | Use it when | Owner |
|---|---|---|
Editable event props | One React editable needs a local browser shortcut or event hook. | @platejs/plite-react |
editor.update((tx) => ...) | A command should change the document, selection, marks, roots, or state. |
@platejs/plite |
Extension commands | A reusable semantic action should compose across browser, programmatic, and test callers. | @platejs/plite |
clipboardHandler(...) contribution | Paste or drop ingress needs package-owned DOM policy. | @platejs/plite-dom |
| DOM coverage boundaries | Model content exists but its DOM is intentionally hidden or virtualized. | @platejs/plite-dom and @platejs/plite-react |
@platejs/browser | A behavior claim needs model, DOM, native selection, focus, trace, screenshot, or follow-up typing proof. | @platejs/browser |
Use Editable for UI-local event interception. Use transactions and extensions for editor behavior that should survive another input path.
Plite edits run through explicit owners.
| Stage | What happens | Owner |
|---|---|---|
| Browser event | The browser sends key, beforeinput, input, paste, cut, drop, focus, drag, or selection events. | Browser |
| Editable handler | Editable runs app handlers and decides whether Plite should continue. | @platejs/plite-react |
| Input import | Plite imports the relevant DOM/native selection when the browser owns the current edit target. | @platejs/plite-react and @platejs/plite-dom |
| Command dispatch | Pure extension command handlers consume, delegate, or compose typed semantic actions. | @platejs/plite |
| Transaction | editor.update((tx) => ...) groups model writes into one runtime change. | @platejs/plite |
| Canonical change | Plite builds one root-aware DocumentChange for the complete transaction. | @platejs/plite |
| Corrections | Built-in and extension corrections repair changed ranges to a deterministic fixed point. | @platejs/plite |
| Commit | Subscribers, history, React, replay, collaboration adapters, and proof tools observe one committed change. | @platejs/plite |
| Render and repair | React renders the new state and exports a valid DOM/native selection when needed. | @platejs/plite-react |
| Proof | Browser tests assert the model, DOM, native selection, focus, trace, and follow-up typing that matter for the claim. | @platejs/browser |
The important rule is simple: user intent can arrive through many browser paths, but Plite behavior should land in the transaction pipeline when it changes editor state.
Editable event props are the right tool for editor-local UI behavior.
import { Editable } from "@platejs/plite-react";
<Editable
onKeyDown={(event, { editor }) => {
if (!(event.metaKey && event.key === "k")) return false;
editor.update((tx) => {
tx.text.insert("link");
});
return true;
}}
/>;import { Editable } from "@platejs/plite-react";
<Editable
onKeyDown={(event, { editor }) => {
if (!(event.metaKey && event.key === "k")) return false;
editor.update((tx) => {
tx.text.insert("link");
});
return true;
}}
/>;Return true when your handler owns the event. Return false when Plite should keep running its default behavior.
Use Plite React Event Handling for the exact handler return contract.
Transactions are the write boundary. They group related changes and publish one commit.
editor.update((tx) => {
tx.text.insert("Hello");
tx.marks.toggle("bold");
tx.selection.collapse({ edge: "end" });
});editor.update((tx) => {
tx.text.insert("Hello");
tx.marks.toggle("bold");
tx.selection.collapse({ edge: "end" });
});Keep writes inside one update when they belong to one user action. That gives history, subscribers, React rendering, change replay, and proof tooling one commit to observe.
Use Transforms for the concept guide and Transforms API for the exact transaction groups.
Reusable semantic behavior belongs in pure extension command handlers when it should apply outside one React event.
import {
defineExtension,
editorCommands,
RangeApi,
} from "@platejs/plite";
const shortcuts = defineExtension("shortcuts", {
commands: ({ handle }) => [
handle(editorCommands.insertText, ({ input, state }) => {
const selection = state.selection();
if (input.text !== " " || !selection || !RangeApi.isCollapsed(selection)) {
return false;
}
return state.transaction((tx) => {
tx.nodes.set({ type: "heading-one" });
tx.text.insert(input.text, input.options);
});
}),
],
});import {
defineExtension,
editorCommands,
RangeApi,
} from "@platejs/plite";
const shortcuts = defineExtension("shortcuts", {
commands: ({ handle }) => [
handle(editorCommands.insertText, ({ input, state }) => {
const selection = state.selection();
if (input.text !== " " || !selection || !RangeApi.isCollapsed(selection)) {
return false;
}
return state.
Use built-in definitions such as editorCommands.insertText,
editorCommands.insertBreak, editorCommands.delete, and
editorCommands.replaceSlice. A handler returns false or an immutable
TransactionSpec. Returning false delegates to the next handler or the
built-in implementation. Use around(descriptor, handler) from the command
factory only when a handler must rewrite input or compose with downstream
behavior.
DocumentChange is the replay boundary. Plite corrects the affected regions
before publishing the final change.
editor.update({ tags: "remote-import" }, (tx) => {
tx.changes.apply(DocumentChange.fromJSON(remoteChange));
});editor.update({ tags: "remote-import" }, (tx) => {
tx.changes.apply(DocumentChange.fromJSON(remoteChange));
});Use Document Changes for replay and mapping. Use Normalizing when a structural edit can leave the document temporarily invalid.
A finished update publishes one commit. Runtime subscribers can observe it, history can batch it, React can render from it, and browser proof can inspect the aftermath.
const unsubscribe = editor.subscribe((_snapshot, change) => {
if (change?.changed.has("document") || change?.dirtyStateKeys.length) {
saveDocument(editor.read.value());
}
});const unsubscribe = editor.subscribe((_snapshot, change) => {
if (change?.changed.has("document") || change?.dirtyStateKeys.length) {
saveDocument(editor.read.value());
}
});React UI should read narrow editor facts through hooks where possible. App services can subscribe to commits when they need persistence, analytics, replay, or sync work.
Model-only tests do not prove browser editing. DOM-only tests do not prove Plite correctness.
import { openExample } from "@platejs/browser/playwright";
const editor = await openExample(page, "plaintext", {
ready: { editor: "visible" },
});
await editor.focus();
await editor.type("Hello");
await editor.assert.text("Hello");
await editor.assert.selection({
anchor: { path: [0, 0], offset: 5 },
focus: { path: [0, 0], offset: 5 },
});
await editor.assert.noDoubleSelectionHighlight();import { openExample } from "@platejs/browser/playwright";
const editor = await openExample(page, "plaintext", {
ready: { editor: "visible" },
});
await editor.focus();
await editor.type("Hello");
await editor.assert.text("Hello");
await editor.assert.selection({
anchor: { path: [0, 0], offset: 5 },
focus: { path: [0, 0], offset: 5 },
});
await editor.assert.noDoubleSelectionHighlight();Use Browser when a claim depends on browser events, focus, native selection, screenshots, clipboard, replay, or follow-up typing.
| Goal | Start with |
|---|---|
| Add one local hotkey | Plite React Event Handling |
| Write a reusable command | Commands and Transforms |
| Change Enter, Backspace, Delete, or typed text behavior | Commands and Extensions |
| Preserve valid document shape | Normalizing |
| Apply document changes from storage or sync | Canonical Change Substrate |
| Debug caret or DOM selection bugs | Selection And DOM |
| Own paste, copy, drop, or fragment import policy | Clipboard And Paste |
| Build comments, highlights, diagnostics, or overlay UI | Projection And Overlays |
| Prove a browser editing claim | Browser |
Done. You can now place an editing behavior in the layer that owns it.