Skip to main content

​
Overview

The Elements namespace provides methods for element-level operations within blocks. Elements are the Slate nodes that make up a block’s content structure. 
import { Elements } from '@yoopta/editor';

// Use with editor instance
Elements.insertElement(editor, {
  blockId: 'accordion-1',
  type: 'accordion-list-item',
  at: 'next'
});

// Or via editor methods
editor.insertElement({
  blockId: 'accordion-1',
  type: 'accordion-list-item'
});

​
Element Creation

​
insertElement

Insert an element into a block. 
function insertElement(
  editor: YooEditor,
  options: InsertElementOptions
): void
​
options
InsertElementOptions
required

​
Examples

// Insert accordion item at next position
editor.insertElement({
  blockId: 'accordion-1',
  type: 'accordion-list-item',
  props: { isExpanded: true },
  at: 'next',
  focus: true
});

// Insert at specific path
editor.insertElement({
  blockId: 'accordion-1',
  type: 'accordion-list-item',
  at: [0, 2], // Path in Slate tree
  props: { isExpanded: false }
});

// Insert at end with children
editor.insertElement({
  blockId: 'accordion-1',
  type: 'accordion-list-item',
  at: 'end',
  children: [
    editor.y('accordion-list-item-heading'),
    editor.y('accordion-list-item-content')
  ]
});

​
Element Modification

​
updateElement

Update element properties or text content. 
function updateElement(
  editor: YooEditor,
  options: UpdateElementOptions
): void
​
options
UpdateElementOptions
required

​
Examples

// Update accordion item by type (finds in selection)
editor.updateElement({
  blockId: 'accordion-1',
  type: 'accordion-list-item',
  props: { isExpanded: false }
});

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

// Update link URL and text (inline element)
editor.updateElement({
  blockId: 'paragraph-1',
  type: 'link',
  props: { url: 'https://example.com', target: '_blank' },
  text: 'Click here'
});

// Update with custom matcher
editor.updateElement({
  blockId: 'accordion-1',
  type: 'accordion-list-item',
  match: (element) => element.props?.id === 'item-5',
  props: { isExpanded: true }
});

// Update mention
editor.updateElement({
  blockId: 'paragraph-1',
  type: 'mention',
  props: { userName: 'Jane Doe', userId: '123' },
  text: '@Jane Doe'
});

​
Element Deletion

​
deleteElement

Delete an element from a block. 
function deleteElement(
  editor: YooEditor,
  options: DeleteElementOptions
): void
​
options
DeleteElementOptions
required

​
Examples

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

// Delete first item found in selection
editor.deleteElement({
  blockId: 'accordion-1',
  type: 'accordion-list-item'
});

// Unwrap link (keep text, remove link)
// Before: "Hello <link>world</link>!"
editor.deleteElement({
  blockId: 'paragraph-1',
  type: 'link',
  mode: 'unwrap'
});
// After: "Hello world!"

// Remove mention entirely
// Before: "Hello <mention>@John</mention>!"
editor.deleteElement({
  blockId: 'paragraph-1',
  type: 'mention',
  mode: 'remove'
});
// After: "Hello !"

// Delete with custom matcher
editor.deleteElement({
  blockId: 'accordion-1',
  type: 'accordion-list-item',
  match: (element) => element.props?.id === 'item-5'
});

// Delete all links from old domain
editor.deleteElement({
  blockId: 'paragraph-1',
  type: 'link',
  match: (element) => element.props?.url?.includes('old-domain.com'),
  mode: 'unwrap'
});

​
Element Retrieval

​
getElement

Get a single element from a block. 
function getElement(
  editor: YooEditor,
  options: GetElementOptions
): SlateElement | null
​
options
GetElementOptions
required
​
return
SlateElement | null
The element or null if not found

​
Examples

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

// Get first accordion item
const firstItem = editor.getElement({
  blockId: 'accordion-1',
  type: 'accordion-list-item',
  path: 'first'
});

// Get element with custom matcher
const activeItem = editor.getElement({
  blockId: 'accordion-1',
  match: (el) => el.type === 'accordion-list-item' && el.props?.isExpanded
});

// Get link at selection
const link = editor.getElement({
  blockId: 'paragraph-1',
  type: 'link',
  path: 'selection'
});

​
getElements

Get multiple elements from a block. 
function getElements(
  editor: YooEditor,
  options: GetElementsOptions
): SlateElement[]
​
options
GetElementsOptions
required
​
return
SlateElement[]
Array of elements (empty array if none found)

​
Examples

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

// Get all expanded items
const expandedItems = editor.getElements({
  blockId: 'accordion-1',
  match: (el) => el.type === 'accordion-list-item' && el.props?.isExpanded
});

// Get all links in paragraph
const links = editor.getElements({
  blockId: 'paragraph-1',
  type: 'link'
});

​
getElementEntry

Get element entry [element, path] from a block. 
function getElementEntry(
  editor: YooEditor,
  options: GetElementEntryOptions
): NodeEntry<SlateElement> | null
​
options
GetElementEntryOptions
required
​
return
NodeEntry<SlateElement> | null
Tuple of [element, path] or null if not found

​
Examples

// Get entry by type and path
const entry = editor.getElementEntry({
  blockId: 'accordion-1',
  type: 'accordion-list-item',
  path: [0, 1]
});

if (entry) {
  const [element, path] = entry;
  console.log('Element at path:', path);
  console.log('Element props:', element.props);
}

​
getElementPath

Get the path of an element in the Slate tree. 
function getElementPath(
  editor: YooEditor,
  options: GetElementPathOptions
): Path | null
​
options
GetElementPathOptions
required
​
return
Path | null
The element’s path or null if not found

​
Examples

// Get path of element
const element = editor.getElement({
  blockId: 'accordion-1',
  type: 'accordion-list-item',
  path: 'first'
});

if (element) {
  const path = editor.getElementPath({
    blockId: 'accordion-1',
    element
  });
  console.log('Element path:', path); // [0, 0]
}

​
getParentElementPath

Get the parent element’s path. 
function getParentElementPath(
  editor: YooEditor,
  options: GetElementPathOptions
): Path | null
Parameters and usage are similar to getElementPath.

​
getElementChildren

Get children of an element. 
function getElementChildren(
  editor: YooEditor,
  options: GetElementChildrenOptions
): Descendant[]
​
options
GetElementChildrenOptions
required

​
getElementRect

Get the DOM bounding rectangle of an element. 
function getElementRect(
  editor: YooEditor,
  options: GetElementRectOptions
): DOMRect | null
​
options
GetElementRectOptions
required

​
Element Validation

​
isElementEmpty

Check if an element has no text content. 
function isElementEmpty(
  editor: YooEditor,
  options: IsElementEmptyOptions
): boolean
​
options
IsElementEmptyOptions
required
​
return
boolean
true if element is empty, false otherwise

​
Examples

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

if (isEmpty) {
  console.log('Content is empty');
}

​
Type Definitions

type SlateElement = {
  id: string;
  type: string;           // kebab-case: "paragraph", "accordion-list-item"
  children: Descendant[];
  props?: {
    nodeType?: 'block' | 'inline' | 'void' | 'inlineVoid';
    [key: string]: unknown;
  };
};

type ElementPath =
  | Path                  // [0, 1] - specific path
  | 'start'               // beginning of block
  | 'end'                 // end of block
  | 'next'                // after current element
  | 'prev'                // before current element
  | 'selection'           // at selection
  | 'first'               // first element of type
  | 'last';               // last element of type

type ElementMatcher = (element: SlateElement) => boolean;

type Path = number[];     // Slate path: [0, 1, 2]

​
Block vs Element

Blocks are top-level content units (Paragraph, Heading, Accordion). Each block has a type in PascalCase.Elements are Slate nodes within blocks (heading-one, accordion-list-item). Elements have type in kebab-case.Blocks contain elements. Use Blocks API for block-level operations, Elements API for fine-grained content manipulation.

​
Common Patterns

​
Working with Accordion Items

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

// Toggle first item
if (items[0]) {
  const isExpanded = items[0].props?.isExpanded;
  editor.updateElement({
    blockId: 'accordion-1',
    type: 'accordion-list-item',
    path: [0, 0],
    props: { isExpanded: !isExpanded }
  });
}

// Add/update link
editor.updateElement({
  blockId: 'paragraph-1',
  type: 'link',
  props: { url: 'https://example.com', target: '_blank' },
  text: 'Visit site'
});

// Remove link (keep text)
editor.deleteElement({
  blockId: 'paragraph-1',
  type: 'link',
  mode: 'unwrap'
});

Build docs developers (and LLMs) love

Get started for freeTalk to us