Elements API

Element-level operations within blocks for Yoopta Editor

Elements API

The Elements API provides element-level operations inside blocks: insert, update, delete, and query. It sits below the Blocks API and works on nodes within a block’s content.

Accessing the API

Import the Elements namespace from @yoopta/editor:

import { Elements } from '@yoopta/editor';

Elements.insertElement(editor, { blockId: 'accordion-1', type: 'accordion-list-item', at: 'end' });
Elements.getElement(editor, { blockId: 'accordion-1', type: 'accordion-list-item', path: [0, 1] });
Elements.deleteElement(editor, { blockId: 'accordion-1', type: 'accordion-list-item', path: [0, 1] });

The same functions are exported by name (insertElement, getElement, …). The YooEditor instance also exposes them without the first editor argument (e.g. editor.insertElement({ ... })).

Type Definitions

type ElementPath = number[] | 'selection' | 'first' | 'last';

---

Methods

insertElement

Creates and inserts a new element into a block.

Elements.insertElement(editor: YooEditor, options: InsertElementOptions): void

Parameters:

• editor — Editor instance (required).
• options.blockId — ID of the block (required).
• options.type — Element type, e.g. 'accordion-list-item', 'link' (required).
• options.props — Properties for the new element; merged with plugin defaults.
• options.children — Child elements; if omitted, plugin defaults are used.
• options.at — Where to insert: 'next' | 'prev' | 'start' | 'end' or number[]; default: selection or [0].
• options.focus — Focus editor after insert; default: false.
• options.select — Select the inserted element; default: false.
• options.text — Text for inline elements (e.g. link); use children for block elements.
• options.match — Custom matcher when using at: 'next' or 'prev'.

Elements.insertElement(editor, {
  blockId: 'accordion-1',
  type: 'accordion-list-item',
  props: { isExpanded: true },
  at: 'end',
  focus: true,
});

---

updateElement

Updates properties (and optionally text) of an existing element.

Elements.updateElement(editor: YooEditor, options: UpdateElementOptions): void

Parameters:

• editor — Editor instance (required).
• options.blockId — ID of the block (required).
• options.type — Element type to update (required).
• options.props — Props to set; merged with existing.
• options.text — New text for inline elements (link, mention); ignored for block elements.
• options.path — Slate path; if omitted, uses selection (inline) or root (block).
• options.match — Custom matcher to find the element.

Elements.updateElement(editor, {
  blockId: 'accordion-1',
  type: 'accordion-list-item',
  props: { isExpanded: true },
  path: [0, 1],
});

---

deleteElement

Removes an element or unwraps it (inline).

Elements.deleteElement(editor: YooEditor, options: DeleteElementOptions): void

Parameters:

• editor — Editor instance (required).
• options.blockId — ID of the block (required).
• options.type — Element type to delete (required).
• options.path — Slate path; if omitted, uses selection (inline) or root (block).
• options.match — Custom matcher to find the element.
• options.mode — For inline only: 'unwrap' (default) or 'remove'. Block elements are always fully removed.

Elements.deleteElement(editor, {
  blockId: 'accordion-1',
  type: 'accordion-list-item',
  path: [0, 1],
});

---

getElement

Returns a single element by type, path, or matcher.

Elements.getElement(editor: YooEditor, options: GetElementOptions): SlateElement | null

Parameters:

• editor — Editor instance (required).
• options.blockId — ID of the block (required).
• options.type — Element type to find.
• options.path — Path: number[] or 'selection' | 'first' | 'last'; default: selection or [0].
• options.match — Custom matcher; overrides type-based search.

Returns: Matching element or null.

const item = Elements.getElement(editor, {
  blockId: 'accordion-1',
  type: 'accordion-list-item',
  path: [0, 1],
});

---

getElements

Returns all elements of a type or matching a condition.

Elements.getElements(editor: YooEditor, options: GetElementsOptions): SlateElement[]

Parameters:

• editor — Editor instance (required).
• options.blockId — ID of the block (required).
• options.type — Element type to find.
• options.match — Custom matcher; use instead of or with type.

Returns: Array of elements; empty if none found.

const items = Elements.getElements(editor, {
  blockId: 'accordion-1',
  type: 'accordion-list-item',
});

---

getElementEntry

Returns element and its Slate path (NodeEntry).

Elements.getElementEntry(
  editor: YooEditor,
  options: GetElementEntryOptions
): NodeEntry<SlateElement> | null

Parameters:

• editor — Editor instance (required).
• options.blockId — ID of the block (required).
• options.type — Element type.
• options.path — Path: number[] or 'selection' | 'first' | 'last'; default: selection or [0].

Returns: [element, path] or null.

const entry = Elements.getElementEntry(editor, {
  blockId: 'accordion-1',
  type: 'accordion-list-item',
  path: [0, 1],
});
if (entry) {
  const [element, path] = entry;
}

---

getElementPath

Returns the Slate path of an element instance.

Elements.getElementPath(editor: YooEditor, options: GetElementPathOptions): Path | null

Parameters:

• editor — Editor instance (required).
• options.blockId — ID of the block (required).
• options.element — The element instance (required).

Returns: Path or null.

const item = Elements.getElement(editor, {
  blockId: 'accordion-1',
  type: 'accordion-list-item',
  path: 'first',
});
if (item) {
  const path = Elements.getElementPath(editor, { blockId: 'accordion-1', element: item });
}

---

getElementRect

Returns the DOM bounding box for a Slate element (domRect and clientRects).

Elements.getElementRect(
  editor: YooEditor,
  options: GetElementRectOptions
): { domRect: DOMRect; clientRects: DOMRectList } | null

Parameters:

• editor — Editor instance (required).
• options.blockId — ID of the block (required).
• options.element — Slate element instance (required).

Returns: Rects for the DOM node, or null if not resolved.

const item = Elements.getElement(editor, { blockId: 'image-1', type: 'image', path: [0] });
if (item) {
  const rect = Elements.getElementRect(editor, { blockId: 'image-1', element: item });
  if (rect) {
    const { width, height } = rect.domRect;
  }
}

---

getParentElementPath

Returns the Slate path of an element’s parent.

Elements.getParentElementPath(editor: YooEditor, options: GetElementPathOptions): Path | null

Parameters:

• editor — Editor instance (required).
• options.blockId — ID of the block (required).
• options.element — The element instance (required).

Returns: Parent path or null.

const parentPath = Elements.getParentElementPath(editor, {
  blockId: 'accordion-1',
  element: contentElement,
});

---

getElementChildren

Returns the children array of an element.

Elements.getElementChildren(
  editor: YooEditor,
  options: GetElementChildrenOptions
): SlateElement['children'] | null

Parameters:

• editor — Editor instance (required).
• options.blockId — ID of the block (required).
• options.type — Element type (required).
• options.path — Path to the element; default: selection or [0].

Returns: Children array or null.

const children = Elements.getElementChildren(editor, {
  blockId: 'accordion-1',
  type: 'accordion-list-item',
  path: [0, 1],
});

---

getRootElement

Returns the root element definition for a given block type (plugin). Each plugin defines one or more elements — the root is either the only element in the map, or the one marked with asRoot: true.

Elements.getRootElement(editor: YooEditor, options: GetRootElementOptions): PluginElement | undefined

Parameters:

• editor — Editor instance (required).
• options.blockType — Plugin type name, PascalCase (required). E.g. 'Paragraph', 'Accordion', 'Image'.

Returns: The root PluginElement definition, or undefined if the plugin doesn’t exist, has no elements, or no element is marked as root in a multi-element plugin.

// Get root element of a single-element plugin
const root = Elements.getRootElement(editor, { blockType: 'Paragraph' });
// => { render: ..., props: { nodeType: 'block' } }

// Check if a plugin's root element is void
const imageRoot = Elements.getRootElement(editor, { blockType: 'Image' });
if (imageRoot?.props?.nodeType === 'void') {
  // handle void element
}

// Multi-element plugin — returns the element with asRoot: true
const accordionRoot = Elements.getRootElement(editor, { blockType: 'Accordion' });
if (accordionRoot?.children) {
  console.log('Child element types:', accordionRoot.children);
}

// Filter plugins by root element node type
const blockPlugins = Object.keys(editor.plugins).filter((type) => {
  const root = Elements.getRootElement(editor, { blockType: type });
  const nodeType = root?.props?.nodeType;
  return nodeType !== 'inline' && nodeType !== 'inlineVoid';
});

---

isElementEmpty

Checks whether an element has no text content.

Elements.isElementEmpty(editor: YooEditor, options: IsElementEmptyOptions): boolean

Parameters:

• editor — Editor instance (required).
• options.blockId — ID of the block (required).
• options.type — Element type (required).
• options.path — Path to the element.

Returns: true if empty, false otherwise.

const isEmpty = Elements.isElementEmpty(editor, {
  blockId: 'accordion-1',
  type: 'accordion-list-item-content',
  path: [0, 1, 1],
});