Skip to main content

@lexical/clipboard

Interfaces​

ClipboardImportConfig​

Defined in: packages/lexical-clipboard/src/ClipboardImportExtension.ts:124

Experimental

Configuration for ClipboardImportExtension.

Extended by​

Properties​

$importMimeType​

$importMimeType: ImportMimeTypeConfig

Defined in: packages/lexical-clipboard/src/ClipboardImportExtension.ts:137

Experimental

The per-MIME-type deserializer stacks used by $insertDataTransferForRichText when handling a paste or drop event.

Merged with [...prev, ...override] per MIME type, matching the behavior of GetClipboardDataExtension.$exportMimeType.

Apps add a stack under a brand-new key to register a brand-new MIME type. Set a priority weight to control where in the iteration it sits relative to the built-ins.

priority​

priority: ImportMimeTypePriority

Defined in: packages/lexical-clipboard/src/ClipboardImportExtension.ts:142

Experimental

See ImportMimeTypePriority. Spread-merged across configs — extensions contribute weights without coordinating with each other.

ClipboardImportOutput​

Defined in: packages/lexical-clipboard/src/ClipboardImportExtension.ts:279

Experimental

Output of ClipboardImportExtension: the merged configuration plus a self-contained $insertDataTransfer function that owns the entire paste-side iteration over the priority list. Apps look this up via peer-dependency and call it directly; $insertDataTransferForRichText delegates to it.

Extends​

Properties​

$importMimeType​

$importMimeType: ImportMimeTypeConfig

Defined in: packages/lexical-clipboard/src/ClipboardImportExtension.ts:137

Experimental

The per-MIME-type deserializer stacks used by $insertDataTransferForRichText when handling a paste or drop event.

Merged with [...prev, ...override] per MIME type, matching the behavior of GetClipboardDataExtension.$exportMimeType.

Apps add a stack under a brand-new key to register a brand-new MIME type. Set a priority weight to control where in the iteration it sits relative to the built-ins.

Inherited from​

ClipboardImportConfig.$importMimeType

priority​

priority: ImportMimeTypePriority

Defined in: packages/lexical-clipboard/src/ClipboardImportExtension.ts:142

Experimental

See ImportMimeTypePriority. Spread-merged across configs — extensions contribute weights without coordinating with each other.

Inherited from​

ClipboardImportConfig.priority

Methods​

$insertDataTransfer()​

$insertDataTransfer(dataTransfer, selection): boolean

Defined in: packages/lexical-clipboard/src/ClipboardImportExtension.ts:285

Experimental

Try every MIME type in priority order against the DataTransfer, invoking the configured stack for the first one that has a non-empty payload. Returns true if any stack claimed the data.

Parameters​
dataTransfer​

DataTransfer

selection​

BaseSelection

Returns​

boolean

GetClipboardDataConfig​

Defined in: packages/lexical-clipboard/src/clipboard.ts:772

Configuration for GetClipboardDataExtension.

Properties​

$exportMimeType​

$exportMimeType: ExportMimeTypeConfig

Defined in: packages/lexical-clipboard/src/clipboard.ts:779

The per-MIME-type serializer stacks used when copying or dragging the current selection out of the editor. See ExportMimeTypeConfig.

Merged with [...prev, ...override]

LexicalClipboardData​

Defined in: packages/lexical-clipboard/src/clipboard.ts:56

Indexable​

[mimeType: string & object]: string | undefined

Properties​

application/x-lexical-editor?​

optional application/x-lexical-editor?: string

Defined in: packages/lexical-clipboard/src/clipboard.ts:58

text/html?​

optional text/html?: string

Defined in: packages/lexical-clipboard/src/clipboard.ts:57

text/plain​

text/plain: string

Defined in: packages/lexical-clipboard/src/clipboard.ts:59

Type Aliases​

ExportMimeTypeConfig​

ExportMimeTypeConfig = { [K in keyof LexicalClipboardData]?: ExportMimeTypeFunction[] }

Defined in: packages/lexical-clipboard/src/clipboard.ts:798

A mapping from MIME type to a stack of ExportMimeTypeFunction.

Each entry is an ordered array; the function at the highest index runs first and may call next() to fall through to the function below it. The default config provides a single fallback handler for 'application/x-lexical-editor', 'text/html', and 'text/plain'.

When GetClipboardDataExtension merges a partial config, new functions are appended to the existing array for each MIME type, so later-registered handlers run before earlier ones (including the defaults) and may delegate to them via next(). To register a brand new MIME type, supply a key not present in the default config; arbitrary string keys are accepted in addition to the keys of LexicalClipboardData.

ExportMimeTypeFunction​

ExportMimeTypeFunction = (selection, next) => null | string

Defined in: packages/lexical-clipboard/src/clipboard.ts:764

A function that produces the serialized representation of a selection for a single MIME type. Functions are arranged in a stack per MIME type (see ExportMimeTypeConfig); the function at the top of the stack is invoked first and may call next() to delegate to the previous function in the stack (typically the default Lexical serializer).

Returning null from the top-most function omits that MIME type from the resulting LexicalClipboardData.

Parameters​

selection​

null | BaseSelection

The selection to serialize, or null if there is none.

next​

() => null | string

Calls the previous handler in the stack and returns its result, or null if there is no previous handler.

Returns​

null | string

The serialized string for this MIME type, or null to omit it.

ImportMimeTypeConfig​

ImportMimeTypeConfig = { [key in keyof LexicalClipboardData | string & {}]?: ImportMimeTypeFunction[] }

Defined in: packages/lexical-clipboard/src/ClipboardImportExtension.ts:89

Experimental

A mapping from MIME type to a stack of ImportMimeTypeFunction.

Each entry is an ordered array; the function at the highest index runs first and may call next() to fall through to the function below it. The default config provides one handler each for 'application/x-lexical-editor', 'text/html', and 'text/plain' that matches the legacy $insertDataTransferForRichText behavior.

When ClipboardImportExtension merges a partial config, new functions are appended to the existing array for each MIME type, so later-registered handlers run before earlier ones (including the defaults) and may delegate to them via next().

ImportMimeTypeFunction​

ImportMimeTypeFunction = (data, selection, $next, dataTransfer) => boolean

Defined in: packages/lexical-clipboard/src/ClipboardImportExtension.ts:65

Experimental

A middleware function in a per-MIME-type clipboard-import stack. Mirrors the shape of ExportMimeTypeFunction on the export side.

  • data is the non-empty string returned by DataTransfer.getData(mime) for this MIME type.
  • selection is the current editor selection at the insertion point.
  • $next defers to the next-lower handler in the stack (i.e. the handler that was registered earlier). Returns true if that handler claimed the data; false if no handler accepted it.
  • dataTransfer is the full DataTransfer the paste/drop came from, so a handler can inspect companion MIME types or attached files in addition to the slot it was invoked for (e.g. peek at 'application/x-vscode-source' while handling 'text/html'). When threading through the new pipeline, pass this into $generateNodesFromDOMViaExtension(dom, { context: [contextValue(ImportSourceDataTransfer, dataTransfer)], }) so rules and preprocessors can read it via ctx.get(ImportSourceDataTransfer).

The function should return true if it consumed the data (the caller stops trying further handlers for this MIME type and does not move on to the next MIME type). Return $next() to delegate. Return false if the function decided not to handle the data after inspecting it (e.g. the JSON namespace didn't match) so a lower-priority handler — or the next MIME type — gets a chance.

Parameters​

data​

string

selection​

BaseSelection

$next​

() => boolean

dataTransfer​

DataTransfer

Returns​

boolean

ImportMimeTypePriority​

ImportMimeTypePriority = { readonly [key in keyof LexicalClipboardData | string & {}]?: number }

Defined in: packages/lexical-clipboard/src/ClipboardImportExtension.ts:113

Experimental

Per-MIME-type ordering weights. Lower numbers run first.

Composable across extensions: each extension contributes weights for its MIME types without needing to coordinate. A partial config that sets {'application/vnd.myapp+json': 5} slots its type between the built-in application/x-lexical-editor (0) and text/html (10) — no need to enumerate the full ordering. mergeConfig spreads pairs (later keys override earlier ones for the same MIME type, so an extension can also re-rank a built-in by repeating its key with a new weight).

Iteration: every MIME type that has a handler stack and is present in the dataTransfer (regardless of whether it has an explicit weight) is tried; MIME types with no explicit weight sort to the end, behind all weighted ones, in lexical order.

Variables​

ClipboardDOMImportExtension​

const ClipboardDOMImportExtension: LexicalExtension<ExtensionConfigBase, "@lexical/clipboard/DOMImport", unknown, unknown>

Defined in: packages/lexical-clipboard/src/ClipboardImportExtension.ts:511

Experimental

Drop-in extension that routes text/html clipboard pastes and drops through the DOMImportExtension pipeline (rules, schemas, preprocessors, overlays) instead of the legacy $generateNodesFromDOM. Add to your extension dependencies along with the per-package import extensions you want active (CoreImportExtension, RichTextImportExtension, etc.).

The original DataTransfer and 'paste' source kind are forwarded into the import context so rules and preprocessors can read them via ctx.get(ImportSourceDataTransfer) / ctx.get(ImportSource).

Equivalent to stacking this text/html handler manually via configExtension(ClipboardImportExtension, {...}).

Example​

import {defineExtension} from 'lexical';
import {ClipboardDOMImportExtension} from '@lexical/clipboard';
import {CoreImportExtension, RichTextImportExtension} from '@lexical/html';

defineExtension({
  name: 'app',
  dependencies: [
    CoreImportExtension,
    RichTextImportExtension,
    ClipboardDOMImportExtension,
  ],
});

ClipboardImportExtension​

const ClipboardImportExtension: LexicalExtension<ClipboardImportConfig, "@lexical/clipboard/Import", ClipboardImportOutput, unknown>

Defined in: packages/lexical-clipboard/src/ClipboardImportExtension.ts:442

Experimental

Mirror of GetClipboardDataExtension for the import direction. Holds a per-MIME-type stack of ImportMimeTypeFunctions.

Example​

Route text/html pastes through DOMImportExtension, leaving the defaults for other MIME types untouched:

import {configExtension, defineExtension, $getEditor} from 'lexical';
import {
  ClipboardImportExtension,
  $insertGeneratedNodes,
} from '@lexical/clipboard';
import {
  contextValue,
  DOMImportExtension,
  ImportSource,
  ImportSourceDataTransfer,
  $generateNodesFromDOMViaExtension,
} from '@lexical/html';

defineExtension({
  name: 'app',
  dependencies: [
    DOMImportExtension,
    configExtension(ClipboardImportExtension, {
      $importMimeType: {
        'text/html': [
          (html, selection, _$next, dataTransfer) => {
            const parser = new DOMParser();
            const dom = parser.parseFromString(html, 'text/html');
            const nodes = $generateNodesFromDOMViaExtension(dom, {
              context: [
                contextValue(ImportSource, 'paste'),
                contextValue(ImportSourceDataTransfer, dataTransfer),
              ],
            });
            $insertGeneratedNodes($getEditor(), nodes, selection);
            return true;
          },
        ],
      },
    }),
  ],
});

DEFAULT_IMPORT_MIME_TYPE​

const DEFAULT_IMPORT_MIME_TYPE: ImportMimeTypeConfig

Defined in: packages/lexical-clipboard/src/ClipboardImportExtension.ts:260

Experimental

The default per-MIME-type handler stacks reproducing the legacy $insertDataTransferForRichText behavior exactly. Stacked extensions append on top of these.

DEFAULT_IMPORT_MIME_TYPE_PRIORITY​

const DEFAULT_IMPORT_MIME_TYPE_PRIORITY: ImportMimeTypePriority

Defined in: packages/lexical-clipboard/src/ClipboardImportExtension.ts:158

Experimental

Default per-MIME-type weights reproducing the legacy $insertDataTransferForRichText ordering:

application/x-lexical-editor (0) → text/html (10) → text/plain (20) → text/uri-list (30).

Gaps between weights let third-party MIME types slot in (e.g. weight 5 to run between lexical and html). Apps can also override built-in weights to demote them.

GetClipboardDataExtension​

const GetClipboardDataExtension: LexicalExtension<GetClipboardDataConfig, "@lexical/clipboard/GetClipboardData", ExportMimeTypeConfig, unknown>

Defined in: packages/lexical-clipboard/src/clipboard.ts:926

Lexical extension that controls how the current selection is serialized into clipboard MIME types when copying or dragging out of the editor.

The extension's config holds an ExportMimeTypeConfig — a stack of ExportMimeTypeFunction per MIME type. Out of the box it provides fallback serializers for 'application/x-lexical-editor', 'text/html', and 'text/plain' that defer to $getLexicalContent, $getHtmlContent, and selection.getTextContent() respectively.

Apps can layer additional handlers on top to customize an existing payload (delegating to the default via next()) or to register an entirely new MIME type. Functions provided through mergeConfig are appended to the existing stack for each MIME type, so a newly registered handler runs first and may fall through to the previously registered handlers via its next argument.

The extension's output is the resolved ExportMimeTypeConfig, which $getClipboardDataFromSelection and $exportMimeTypeFromSelection read via the editor's peer dependency lookup.

Example​

import {configExtension, defineExtension} from '@lexical/extension';
import {GetClipboardDataExtension} from '@lexical/clipboard';

const MyClipboardExtension = defineExtension({
  name: 'my-app/clipboard',
  dependencies: [
    configExtension(GetClipboardDataExtension, {
      $exportMimeType: {
        // Wrap the default HTML output with an app-specific marker.
        'text/html': [
          (selection, next) => {
            const html = next();
            return html ? wrapWithMyAppMarker(html) : html;
          },
        ],
        // Add a brand-new MIME type.
        'application/vnd.myapp+json': [
          (selection) =>
            selection ? exportMyAppFormat(selection) : null,
        ],
      },
    }),
  ],
});

Functions​

$exportMimeTypeFromSelection()​

$exportMimeTypeFromSelection(mimeType, selection?): string | null

Defined in: packages/lexical-clipboard/src/clipboard.ts:866

Serialize the given selection for a single MIME type using the active editor's configured ExportMimeTypeConfig. The configured stack is read from GetClipboardDataExtension via the editor's peer dependency lookup; if the extension was not built into the editor, the default stack is used.

Useful when only one MIME representation is needed rather than the full LexicalClipboardData produced by $getClipboardDataFromSelection.

Must be called from within an editor update or read.

Parameters​

mimeType​

keyof LexicalClipboardData

The MIME type to serialize, e.g. 'text/html', 'application/x-lexical-editor', 'text/plain', or any custom key registered in the ExportMimeTypeConfig.

selection?​

BaseSelection | null

The selection to serialize (defaults to $getSelection()).

Returns​

string | null

The serialized string for the requested MIME type, or null if no handler is registered for it or every handler returned null.

$generateJSONFromSelectedNodes()​

$generateJSONFromSelectedNodes<SerializedNode>(editor, selection): object

Defined in: packages/lexical-clipboard/src/clipboard.ts:547

Gets the Lexical JSON of the nodes inside the provided Selection.

Type Parameters​

SerializedNode​

SerializedNode extends BaseSerializedNode

Parameters​

editor​

LexicalEditor

LexicalEditor to get the JSON content from.

selection​

BaseSelection | null

Selection to get the JSON content from.

Returns​

object

an object with the editor namespace and a list of serializable nodes as JavaScript objects.

namespace​

namespace: string

nodes​

nodes: SerializedNode[]

$generateNodesFromSerializedNodes()​

$generateNodesFromSerializedNodes(serializedNodes): LexicalNode[]

Defined in: packages/lexical-clipboard/src/clipboard.ts:577

This method takes an array of objects conforming to the BaseSerializedNode interface and returns an Array containing instances of the corresponding LexicalNode classes registered on the editor. Normally, you'd get an Array of BaseSerialized nodes from $generateJSONFromSelectedNodes

Parameters​

serializedNodes​

BaseSerializedNode[]

an Array of objects conforming to the BaseSerializedNode interface.

Returns​

LexicalNode[]

an Array of Lexical Node objects.

$getClipboardDataFromSelection()​

$getClipboardDataFromSelection(selection?): LexicalClipboardData

Defined in: packages/lexical-clipboard/src/clipboard.ts:716

Serialize the content of the current selection to strings in text/plain, text/html, and application/x-lexical-editor (Lexical JSON) formats (as available).

Parameters​

selection?​

BaseSelection | null

the selection to serialize (defaults to $getSelection())

Returns​

LexicalClipboardData

LexicalClipboardData

$getHtmlContent()​

$getHtmlContent(editor, selection?): string

Defined in: packages/lexical-clipboard/src/clipboard.ts:73

Returns the currently selected Lexical content as an HTML string, relying on the logic defined in the exportDOM methods on the LexicalNode classes. Note that this will not return the HTML content of the entire editor (unless all the content is included in the current selection).

Parameters​

editor​

LexicalEditor

LexicalEditor instance to get HTML content from

selection?​

BaseSelection | null

The selection to use (default is $getSelection())

Returns​

string

a string of HTML content

$getLexicalContent()​

$getLexicalContent(editor, selection?): string | null

Defined in: packages/lexical-clipboard/src/clipboard.ts:102

Returns the currently selected Lexical content as a JSON string, relying on the logic defined in the exportJSON methods on the LexicalNode classes. Note that this will not return the JSON content of the entire editor (unless all the content is included in the current selection).

Parameters​

editor​

LexicalEditor

LexicalEditor instance to get the JSON content from

selection?​

BaseSelection | null

The selection to use (default is $getSelection())

Returns​

string | null

$handlePlainTextDrop()​

$handlePlainTextDrop(event, editor): boolean

Defined in: packages/lexical-clipboard/src/clipboard.ts:376

Drop handler for plain-text editors. Same semantics as $handleRichTextDrop but inserts via $insertDataTransferForPlainText.

Parameters​

event​

DragEvent

editor​

LexicalEditor

Returns​

boolean

$handleRichTextDrop()​

$handleRichTextDrop(event, editor): boolean

Defined in: packages/lexical-clipboard/src/clipboard.ts:364

Drop handler for rich-text editors. Inserts the DataTransfer payload via $insertDataTransferForRichText at the drop caret and, when the drag originated from a Lexical editor (marked via $writeDragSourceToDataTransfer on DRAGSTART), removes the source range — producing cut-and-paste semantics whether the drop is in the same editor or a different one on the same page.

Parameters​

event​

DragEvent

editor​

LexicalEditor

Returns​

boolean

$insertDataTransferForPlainText()​

$insertDataTransferForPlainText(dataTransfer, selection): void

Defined in: packages/lexical-clipboard/src/clipboard.ts:129

Attempts to insert content of the mime-types text/plain or text/uri-list from the provided DataTransfer object into the editor at the provided selection. text/uri-list is only used if text/plain is not also provided.

Parameters​

dataTransfer​

DataTransfer

an object conforming to the [DataTransfer interface] (https://html.spec.whatwg.org/multipage/dnd.html#the-datatransfer-interface)

selection​

BaseSelection

the selection to use as the insertion point for the content in the DataTransfer object

Returns​

void

$insertDataTransferForRichText()​

$insertDataTransferForRichText(dataTransfer, selection, _editor?): void

Defined in: packages/lexical-clipboard/src/clipboard.ts:151

Insert the contents of dataTransfer at selection using the rich-text import pipeline (application/x-lexical-editor → text/html → text/plain → text/uri-list, in descending order of priority).

Parameters​

dataTransfer​

DataTransfer

an object conforming to the [DataTransfer interface] (https://html.spec.whatwg.org/multipage/dnd.html#the-datatransfer-interface)

selection​

BaseSelection

the selection to use as the insertion point for the content in the DataTransfer object

_editor?​

LexicalEditor

unused; retained for backwards compatibility. Safe to omit on new call sites.

Returns​

void

$insertGeneratedNodes()​

$insertGeneratedNodes(editor, nodes, selection): void

Defined in: packages/lexical-clipboard/src/clipboard.ts:395

Inserts Lexical nodes into the editor using different strategies depending on some simple selection-based heuristics. If you're looking for a generic way to to insert nodes into the editor at a specific selection point, you probably want lexical.$insertNodes

Parameters​

editor​

LexicalEditor

LexicalEditor instance to insert the nodes into.

nodes​

LexicalNode[]

The nodes to insert.

selection​

BaseSelection

The selection to insert the nodes into.

Returns​

void

$writeDragSourceToDataTransfer()​

$writeDragSourceToDataTransfer(dataTransfer, editor): void

Defined in: packages/lexical-clipboard/src/clipboard.ts:181

Populate dataTransfer with a marker identifying the current editor as a drag source. Pair this with $handleRichTextDrop or $handlePlainTextDrop on the drop side to get cut-and-paste semantics for drags that end in a different editor.

Only the source editor's key needs to round-trip — the source's RangeSelection itself is preserved on the source editor between drag start and drop (Lexical suppresses selectionchange during drag), so the drop handler reads it directly via $getSelection() on the resolved source editor.

Callers typically invoke this from a DRAGSTART_COMMAND handler alongside setLexicalClipboardDataTransfer (so that the dragged content itself round-trips with full node fidelity).

Parameters​

dataTransfer​

DataTransfer

editor​

LexicalEditor

Returns​

void

copyToClipboard()​

copyToClipboard(editor, event, data?): Promise<boolean>

Defined in: packages/lexical-clipboard/src/clipboard.ts:601

Copies the content of the current selection to the clipboard in text/plain, text/html, and application/x-lexical-editor (Lexical JSON) formats.

Parameters​

editor​

LexicalEditor

the LexicalEditor instance to copy content from

event​

ClipboardEvent | null

the native browser ClipboardEvent to add the content to.

data?​

LexicalClipboardData

Returns​

Promise<boolean>

setLexicalClipboardDataTransfer()​

setLexicalClipboardDataTransfer(clipboardData, data): void

Defined in: packages/lexical-clipboard/src/clipboard.ts:732

Call setData on the given clipboardData for each MIME type present in the given data (from $getClipboardDataFromSelection)

Parameters​

clipboardData​

DataTransfer

the event.clipboardData to populate from data

data​

LexicalClipboardData

The lexical data

Returns​

void