Skip to main content

​
Overview

The toggleBlock method transforms a block to a different type (e.g., Paragraph → Heading) or inserts an element in the current leaf, depending on the scope.

​
Signature

Blocks.toggleBlock(
  editor: YooEditor,
  type: string,
  options?: ToggleBlockOptions
): string

​
Parameters

​
editor
YooEditor
required
The editor instance
​
type
string
required
Target block/element type to toggle to (must be a registered plugin type)
​
options
ToggleBlockOptions
Configuration object for toggling

​
Return Value

Returns the ID of the toggled block (or original block ID if scope is ‘element’).

​
Examples

​
Transform Block Type

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

// Transform paragraph to heading
Blocks.toggleBlock(editor, 'Heading', {
  preserveContent: true,
});

// Transform to same type (toggles back to Paragraph)
Blocks.toggleBlock(editor, 'Paragraph', {
  scope: 'block',
});

​
Insert Element in Leaf

// Insert element in current leaf (e.g., in callout content)
Blocks.toggleBlock(editor, 'Paragraph', {
  scope: 'element',
  preserveContent: true,
});

​
Auto Scope Detection

// Automatically determines scope based on context
// If current element has injectElementsFromPlugins → element scope
// Otherwise → block scope
Blocks.toggleBlock(editor, 'Heading', {
  scope: 'auto', // default
});

​
Toggle with Custom Structure

// Toggle with custom element structure
Blocks.toggleBlock(editor, 'Accordion', {
  elements: editor.y('accordion-list', {
    children: [
      editor.y('accordion-list-item', {
        props: { isExpanded: true },
        children: [
          editor.y('accordion-list-item-heading'),
          editor.y('accordion-list-item-content')
        ]
      })
    ]
  }),
});

​
Use Cases

​
Toggle Paragraph to Heading

const makeHeading = (editor: YooEditor, level: 1 | 2 | 3) => {
  Blocks.toggleBlock(editor, 'Heading', {
    scope: 'block',
    preserveContent: true,
    focus: true,
  });
  
  // Then update to specific heading level
  const block = Blocks.getBlock(editor, { at: editor.path.current });
  if (block) {
    // Update heading level via Elements API
    editor.updateElement({
      blockId: block.id,
      type: `heading-${level}`,
      props: { level },
    });
  }
};

​
Toggle Back to Paragraph

const makeParagraph = (editor: YooEditor) => {
  Blocks.toggleBlock(editor, 'Paragraph', {
    scope: 'block',
    preserveContent: true,
  });
};

​
Notes

When scope is 'block', the entire block is transformed. When scope is 'element', an element is inserted in the current leaf (only works if the current element has injectElementsFromPlugins).
If toggling to the same type in block scope, it will toggle back to the default block type (Paragraph).
The preserveContent option extracts text nodes and transfers them to the new block/element structure.
If the target plugin type doesn’t exist, an error will be thrown.
The method automatically determines the appropriate root element type for the target plugin if not specified in elements.

​
Type Definition

type ToggleBlockOptions = {
  at?: number; // YooptaPathIndex
  scope?: 'auto' | 'block' | 'element';
  preserveContent?: boolean;
  focus?: boolean;
  elements?: SlateElement;
};

updateBlock

Update block after toggle

splitBlock

Split before toggling