> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yoopta.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`:

```typescript theme={null}
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] });
```

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

## Type Definitions

```typescript theme={null}
type ElementPath = number[] | 'selection' | 'first' | 'last';
```

***

## Methods

### insertElement

Creates and inserts a new element into a block.

```typescript theme={null}
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'`.

```typescript theme={null}
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.

```typescript theme={null}
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.

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

***

### deleteElement

Removes an element or unwraps it (inline).

```typescript theme={null}
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.

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

***

### getElement

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

```typescript theme={null}
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`.

```typescript theme={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.

```typescript theme={null}
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.

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

***

### getElementEntry

Returns element and its Slate path (`NodeEntry`).

```typescript theme={null}
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`.

```typescript theme={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.

```typescript theme={null}
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`.

```typescript theme={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`).

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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`.

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

***

### getElementChildren

Returns the children array of an element.

```typescript theme={null}
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`.

```typescript theme={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`.

```typescript theme={null}
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.

```typescript theme={null}
// 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.

```typescript theme={null}
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.

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