Clipboard And Paste

Clipboard work crosses browser events, Slate fragments, transactions, DOM coverage, and browser proof. Use this page to decide whether a paste, copy, or drop policy belongs in Editable, an extension, editor.api.clipboard, or a fragment transform.

Choose The Right Surface

Paste bugs usually come from mixing browser event ownership with model insertion ownership.

Use Editable for local event interception. Use extension clipboard policy when the behavior should apply to native paste, drop, browser tests, and every React surface that installs the extension.

Runtime Pipeline

Clipboard data enters Slate through explicit layers.

Do not close a paste bug with only a model assertion when the failure was in the browser event, DOM clipboard payload, native selection, or follow-up typing.

Extension Clipboard Policy

Use clipboard.insertData when a feature owns a reusable import rule.

import { defineEditorExtension } from "@platejs/slate";
 
const pasteTodoPrefix = defineEditorExtension({
  name: "paste-todo-prefix",
  clipboard: {
    insertData(data, { editor, next }) {
      const text = data.getData("text/plain");
 
      if (!text.startsWith("todo:")) {
        return next();
      }
 
      editor.update((tx) => {
        tx.text.insert(text.slice("todo:".length).trim());
      });
 
      return true;
    },
  },
});Copy

import { defineEditorExtension } from "@platejs/slate";
 
const pasteTodoPrefix = defineEditorExtension({
  name: "paste-todo-prefix",
  clipboard: {
    insertData(data, { editor, next }) {
      const text = data.getData("text/plain");
 
      if (!text.startsWith("todo:")) {
        return next();
      }
 
      editor.update((tx) => {
        tx.text.insert(text.slice("todo:".length).trim());
      });
 
      return true;
    },
  },
});Copy

Return true when the extension handled the payload. Return next() when Slate should keep running the internal fragment and plain-text import path.

Use this for package-owned import rules such as custom inline syntax, pasted URLs, product fragments, and table-specific paste policy. Do not put those rules in Slate core unless the rule is part of Slate's model contract.

DOM Clipboard API

React editors expose DOM clipboard helpers through editor.api.clipboard.

editor.api.clipboard.insertData(dataTransfer);
editor.api.clipboard.insertFragmentData(dataTransfer);
editor.api.clipboard.insertTextData(dataTransfer);
editor.api.clipboard.writeSelection(dataTransfer);Copy

editor.api.clipboard.insertData(dataTransfer);
editor.api.clipboard.insertFragmentData(dataTransfer);
editor.api.clipboard.insertTextData(dataTransfer);
editor.api.clipboard.writeSelection(dataTransfer);Copy

Use these APIs from framework bridges, tests, or low-level event code that already has a DataTransfer. Product commands should still write model state through editor.update((tx) => ...).

Slate writes plain text, HTML, and an internal Slate fragment payload. The fragment payload uses application/${clipboardFormatKey}, so editors with different keys do not blindly import each other's internal JSON.

Fragment Insertion

Fragments are Slate node slices. Insert them with tx.fragment.insert(...) when the payload is already decoded.

editor.update((tx) => {
  tx.fragment.insert([
    {
      type: "paragraph",
      children: [{ text: "Pasted paragraph" }],
    },
  ]);
});Copy

editor.update((tx) => {
  tx.fragment.insert([
    {
      type: "paragraph",
      children: [{ text: "Pasted paragraph" }],
    },
  ]);
});Copy

Core fragment insertion is structural. Grid-aware table paste, spreadsheet mapping, and product-specific merge rules belong in the table or product extension that understands those structures.

Hidden And Projected Content

Copy and drag can involve model content whose DOM is hidden, staged, or virtualized. DOM coverage boundaries decide whether hidden content participates in copy, find, and selection conversion.

Use DOM Coverage Boundaries for copyPolicy, findPolicy, selectionPolicy, and materialization behavior. Use Selection And DOM when a copy or paste bug also depends on caret position or native selection repair.

Browser Proof

Clipboard proof should name the layer that can fail.

Use Slate Browser for clipboard helpers and Editing Behavior for the full event-to-commit pipeline.

Related Docs

• Editable Component
• React Editor
• Slate DOM
• DOM Coverage Boundaries
• Operation Replay Substrate
• Transforms API