Inserter

Inserts HTML, nodes, blocks, and fragments at the caret, target element, or editor edges.

Access:

app.getService('inserter')

App code:

const inserter = app.getService('inserter');

Plugin:

const inserter = this.app.getService('inserter');

insertHtml#

Cleans and normalizes HTML into a fragment, then inserts it according to the current selection context (caret, multi-block, list merge, replace-all, or target element).

Parameters:

• html (string) — HTML string
• options (object) — object with the keys below
  • caret (any) — caret placement after insert: 'before', 'after' (default), or false to leave selection untouched
  • target (string) — element or CSS selector to insert relative to instead of the current caret position
  • targetPosition (string) — 'before' or 'after' the target element (default 'after')
  • focus (boolean) — focus the resulting block after insert (default true)
  • truncate (boolean) — trim a trailing empty text node/line left behind by the split (default true)
  • split (boolean) — split the current element at the caret before inserting (default true)

Returns: { nodes: Node[], blocks: Block[] }

inserter.insertHtml('<p>Hello</p>');

insertBlock#

Inserts a block instance at the caret or target, wrapping inline blocks in a text block when needed and registering the block in the blocks collection.

Parameters:

• block (Block | HTMLElement) — block instance
• options (object) — object with the keys below
  • caret (any) — caret placement after insert: 'before', 'after' (default), or false to leave selection untouched
  • target (string) — element or CSS selector to insert relative to instead of the current caret position
  • targetPosition (string) — 'before' or 'after' the target element (default 'after')
  • focus (boolean) — focus the resulting block after insert (default true)
  • truncate (boolean) — trim a trailing empty text node/line left behind by the split (default true)
  • split (boolean) — split the current element at the caret before inserting (default true)

Returns: { nodes: Node[], blocks: Block[] }

inserter.insertBlock(imageBlock);

insertNodes#

Wraps one or more DOM nodes in a fragment and inserts them using the shared payload insertion pipeline.

Parameters:

• nodes (Array) — nodes
• options (object) — object with the keys below
  • caret (any) — caret placement after insert: 'before', 'after' (default), or false to leave selection untouched
  • target (string) — element or CSS selector to insert relative to instead of the current caret position
  • targetPosition (string) — 'before' or 'after' the target element (default 'after')
  • focus (boolean) — focus the resulting block after insert (default true)
  • truncate (boolean) — trim a trailing empty text node/line left behind by the split (default true)
  • split (boolean) — split the current element at the caret before inserting (default true)

Returns: { nodes: Node[], blocks: Block[] }

inserter.insertNodes([textNode, br]);

insertFragment#

Inserts a DocumentFragment via the shared payload pipeline, detecting block-level vs line-level content automatically.

Parameters:

• fragment (object) — DocumentFragment to insert or process
• options (object) — object with the keys below
  • caret (any) — caret placement after insert: 'before', 'after' (default), or false to leave selection untouched
  • target (string) — element or CSS selector to insert relative to instead of the current caret position
  • targetPosition (string) — 'before' or 'after' the target element (default 'after')
  • focus (boolean) — focus the resulting block after insert (default true)
  • truncate (boolean) — trim a trailing empty text node/line left behind by the split (default true)
  • split (boolean) — split the current element at the caret before inserting (default true)

Returns: { nodes: Node[], blocks: Block[] }

inserter.insertFragment(fragment);

insertJson#

Deserializes block JSON via contentParser.fromJSON into a fragment and inserts it as block-level content.

Parameters:

• json (object | string) — JSON
• options (object) — object with the keys below
  • caret (any) — caret placement after insert: 'before', 'after' (default), or false to leave selection untouched
  • target (string) — element or CSS selector to insert relative to instead of the current caret position
  • targetPosition (string) — 'before' or 'after' the target element (default 'after')
  • focus (boolean) — focus the resulting block after insert (default true)
  • truncate (boolean) — trim a trailing empty text node/line left behind by the split (default true)
  • split (boolean) — split the current element at the caret before inserting (default true)

Returns: { nodes: Node[], blocks: Block[] }

inserter.insertJson([{ type: 'paragraph', text: 'Hi' }]);

insertText#

Inserts a text node at the current collapsed caret inside an editable block, optionally placing the caret before or after it.

Parameters:

• text (string) — text
• options (object) — object with the keys below
  • caret (any) — 'after' (default), 'before', or false to skip moving the caret

Returns: { nodes: Node[], blocks: Block[] }

inserter.insertText('Hello');

insertNode#

Inserts a single DOM node at the current caret inside an editable block (excluding pre blocks), then focuses the containing block or clears selection when caret is false.

Parameters:

• node (HTMLElement | string) — DOM node
• options (object) — object with the keys below
  • caret (any) — 'after' (default), 'before', or false to clear the selection without placing the caret

Returns: { nodes: Node[], blocks: Block[] }

inserter.insertNode(imgEl);

insertBreakline#

Inserts a br element at the caret inside the current editable block, optionally splitting the top inline element first; returns empty result for multi-block selections.

Parameters:

• options (object) — object with the keys below
  • truncate (boolean) — when not false, truncate the range before insert if needed (default true)
  • split (boolean) — when not false, split the top inline wrapper at the caret before inserting the br (default true)
  • caret (any) — 'after' (default), 'before', or false to skip moving the caret

Returns: { nodes: Node[], blocks: Block[] }

inserter.insertBreakline();

insertBreaklinePlain#

Inserts a br at the current range without requiring a single-block editable context, with optional inline splitting and truncation.

Parameters:

• options (object) — object with the keys below
  • truncate (boolean) — when not false, truncate the range before insert if needed (default true)
  • split (boolean) — when not false, split the top inline wrapper at the caret before inserting the br (default true)
  • caret (any) — 'after' (default), 'before', or false to skip moving the caret

Returns: { nodes: Node[], blocks: Block[] }

inserter.insertBreaklinePlain();

insertNewline#

Inserts a literal newline text node when the caret is inside a pre block.

Parameters:

• options (object) — object with the keys below
  • caret (any) — caret placement after insert (forwarded to the text-node insert helper)

Returns: { nodes: Node[], blocks: Block[] }

inserter.insertNewline();

insertClientPoint#

Creates a collapsed range from mouse/touch client coordinates and sets it as the editor selection when the point is inside the editable root.

Parameters:

• e (Event) — native DOM event

Returns: boolean

inserter.insertClientPoint(event);

replaceBlockHtml#

Replaces a block element with new HTML content: removes the old block, inserts parsed roots, mounts blocks, and focuses the last inserted block unless focus is disabled.

Parameters:

• block (Block | HTMLElement) — block instance
• html (string) — HTML string
• options (object) — object with the keys below
  • focus (boolean) — when not false, focus the last inserted block (or place caret after inserted roots) (default true)

Returns: { nodes: Node[], blocks: Block[] }

inserter.replaceBlockHtml(block, '<p>New content</p>');