Skip to main content

​
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],
});