Skip to main content

​
Overview

The updateElement method modifies properties of an existing element within a block.

​
Signature

editor.updateElement(options: UpdateElementOptions): void

​
Parameters

​
options
UpdateElementOptions
required
Configuration object for updating the element

​
Examples

​
Basic Usage

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

function AccordionItem({ blockId, itemPath }: Props) {
  const editor = useYooptaEditor();

  const toggleExpanded = () => {
    const item = editor.getElement({
      blockId,
      type: 'accordion-list-item',
      path: itemPath,
    });

    editor.updateElement({
      blockId,
      type: 'accordion-list-item',
      props: { isExpanded: !item?.props?.isExpanded },
      path: itemPath,
    });
  };

  return <button onClick={toggleExpanded}>Toggle</button>;
}

​
Update with Matcher

// Update active tab
editor.updateElement({
  blockId: 'tabs-1',
  type: 'tabs-item-heading',
  props: { active: false },
  match: (el) => el.type === 'tabs-item-heading' && el.props?.active === true,
});

// Update link at current selection
editor.updateElement({
  blockId: 'paragraph-1',
  type: 'link',
  props: { url: 'https://example.com', target: '_blank' },
  // If path not specified, finds link in current selection
});

// Update link text and URL
editor.updateElement({
  blockId: 'paragraph-1',
  type: 'link',
  props: { url: 'https://new-url.com' },
  text: 'New link text', // Updates the displayed text
});

// Update link by path
editor.updateElement({
  blockId: 'paragraph-1',
  type: 'link',
  props: { url: 'https://example.com' },
  path: [0, 2], // Direct path to link element
});

​
Update by Path

// Update at specific path
editor.updateElement({
  blockId: 'table-1',
  type: 'table-data-cell',
  props: { width: 300, asHeader: true },
  path: [0, 0, 0],
});

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

​
Use Cases

​
Toggle Accordion Item

const toggleAccordionItem = (blockId: string, itemPath: number[]) => {
  const item = editor.getElement({
    blockId,
    type: 'accordion-list-item',
    path: itemPath,
  });

  if (item) {
    editor.updateElement({
      blockId,
      type: 'accordion-list-item',
      props: { isExpanded: !item.props?.isExpanded },
      path: itemPath,
    });
  }
};

​
Set Active Tab

const setActiveTab = (blockId: string, tabId: string) => {
  // Deactivate all tabs
  const allTabs = editor.getElements({
    blockId,
    type: 'tabs-item-heading',
  });

  allTabs.forEach((tab, index) => {
    editor.updateElement({
      blockId,
      type: 'tabs-item-heading',
      props: { active: tab.id === tabId },
      path: [0, 0, index],
    });
  });
};

​
Update Table Cell

const updateCellProperties = (
  blockId: string,
  cellPath: number[],
  properties: { width?: number; asHeader?: boolean; align?: string },
) => {
  editor.updateElement({
    blockId,
    type: 'table-data-cell',
    props: properties,
    path: cellPath,
  });
};

​
Update Step Completion

const markStepComplete = (blockId: string, stepIndex: number) => {
  editor.updateElement({
    blockId,
    type: 'step-list-item',
    props: { isCompleted: true },
    path: [0, 0, stepIndex],
  });
};

​
Update Mention Element

// Update mention at selection
editor.updateElement({
  blockId: 'paragraph-1',
  type: 'mention',
  props: { name: 'Jane Doe', id: 'user-123' },
  text: '@Jane Doe', // Update displayed text
});

​
Advanced Usage

​
Update Multiple Elements

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

  items.forEach((item, index) => {
    editor.updateElement({
      blockId,
      type: 'accordion-list-item',
      props: { isExpanded: true },
      path: [0, 0, index],
    });
  });
};

​
Conditional Update

const updateIfNotEmpty = (blockId: string, itemPath: number[]) => {
  const isEmpty = editor.isElementEmpty({
    blockId,
    type: 'accordion-list-item-content',
    path: [...itemPath, 1],
  });

  if (!isEmpty) {
    editor.updateElement({
      blockId,
      type: 'accordion-list-item',
      props: { hasContent: true },
      path: itemPath,
    });
  }
};

​
Notes

Properties are merged with existing props. To remove a property, set it to undefined or null.
For inline elements (like link, mention), if path is not specified, the method will automatically search for the element in the current selection. This makes it easy to update links or mentions where the cursor is positioned.
The text parameter is only supported for inline elements. For block elements, use insertElement or updateBlock to modify content.
If the element is not found (no match for type, path, or matcher), the operation will fail with a console warning. Always check if the element exists before updating if you’re unsure.
When using a custom match function, it searches for the element in the current selection. The function receives each element and should return true for the element you want to update.

​
Type Definition

type UpdateElementOptions = {
  blockId: string;
  type: string;
  props?: Record<string, unknown>;
  text?: string; // Only for inline elements
  path?: number[]; // Direct Slate path
  match?: (element: SlateElement) => boolean;
};

getElement

Get element before updating

insertElement

Create new elements

deleteElement

Remove elements

isElementEmpty

Check element state before update