Skip to main content

​
Overview

Yoopta Editor v6 introduces significant API and architectural changes compared to v4.9.x. This guide helps you migrate existing projects to the latest version.
Version 6.0.0 was released on February 24, 2026 and graduated from beta (6.0.0-beta.22) with no feature changes.

​
Breaking Changes Summary

​
1. Editor Creation

v4.9.x: 
<YooptaEditor
  plugins={plugins}
  marks={marks}
  value={value}
  onChange={setValue}
/>
v6: 
const editor = createYooptaEditor({ plugins, marks });

<YooptaEditor editor={editor} onChange={handleChange}>
  {/* UI components as children */}
</YooptaEditor>

​
2. Value Management

v4.9.x:
  • value prop on <YooptaEditor>
  • Controlled component pattern
v6:
  • No value prop
  • Set initial value with createYooptaEditor({ value }) or editor.setEditorValue()
  • Read value from onChange callback or editor.getEditorValue()

​
3. UI Components

v4.9.x:
  • @yoopta/tools package
  • tools={[...]} prop
v6:
  • @yoopta/ui package
  • UI components as children of <YooptaEditor>

​
Step-by-Step Migration

​
Step 1: Update Dependencies

Update to the latest versions: 
# Update core packages
npm install @yoopta/editor@latest

# Update all plugins
npm install @yoopta/paragraph@latest @yoopta/headings@latest
# ... update other plugins

# Install UI package (replaces @yoopta/tools)
npm install @yoopta/ui@latest

# Uninstall deprecated packages
npm uninstall @yoopta/tools

# Optional: Install theme
npm install @yoopta/themes-shadcn@latest

​
Step 2: Create Editor Instance

Move editor configuration outside the component: Before (v4.9.x): 
import { YooptaEditor } from '@yoopta/editor';
import Paragraph from '@yoopta/paragraph';

function Editor() {
  const [value, setValue] = useState(initialValue);
  
  return (
    <YooptaEditor
      plugins={[Paragraph, /* ... */]}
      marks={MARKS}
      value={value}
      onChange={setValue}
    />
  );
}
After (v6): 
import { useMemo } from 'react';
import { createYooptaEditor, YooptaEditor } from '@yoopta/editor';
import Paragraph from '@yoopta/paragraph';

const PLUGINS = [Paragraph, /* ... */];

function Editor() {
  const editor = useMemo(
    () => createYooptaEditor({
      plugins: PLUGINS,
      marks: MARKS,
    }),
    []
  );
  
  // Set initial value
  useEffect(() => {
    editor.setEditorValue(initialValue);
  }, []);
  
  const handleChange = (value: YooptaContentValue) => {
    // Save or process value
    setValue(value);
  };
  
  return (
    <YooptaEditor editor={editor} onChange={handleChange}>
      {/* UI components */}
    </YooptaEditor>
  );
}

​
Step 3: Update UI Components

Replace @yoopta/tools with @yoopta/ui components as children: Before (v4.9.x): 
import { Toolbar, ActionMenu } from '@yoopta/tools';

<YooptaEditor
  plugins={plugins}
  tools={[Toolbar, ActionMenu]}
  // ...
/>
After (v6): 
import {
  FloatingToolbar,
  ActionMenuList,
  SlashCommandMenu,
  FloatingBlockActions,
} from '@yoopta/ui';

<YooptaEditor editor={editor} onChange={handleChange}>
  <FloatingToolbar />
  <ActionMenuList />
  <SlashCommandMenu />
  <FloatingBlockActions />
</YooptaEditor>

​
Step 4: Apply Themes (Optional)

Use theme packages for pre-styled UI: 
import { applyTheme } from '@yoopta/themes-shadcn';
import Paragraph from '@yoopta/paragraph';
import HeadingOne from '@yoopta/headings/HeadingOne';

const PLUGINS = applyTheme([Paragraph, HeadingOne, /* ... */]);

const editor = createYooptaEditor({
  plugins: PLUGINS,
  marks: MARKS,
});
Import theme CSS: 
import '@yoopta/themes-shadcn/styles.css';
// Optional: Import variables if you don't have shadcn setup
import '@yoopta/themes-shadcn/variables.css';

​
Step 5: Update API Calls

Update deprecated API methods: Removed Methods:
v4.9.xv6 Replacement
editor.applyChangeseditor.applyTransforms
editor.selectioneditor.path
editor.setSelectioneditor.setPath
editor.setBlockSelectededitor.setPath
editor.insertBlockseditor.batchOperations(() => { /* multiple insertBlock */ })
editor.deleteBlockseditor.batchOperations(() => { /* multiple deleteBlock */ })
editor.createBlockeditor.insertBlock
Example: 
// Before (v4.9.x)
editor.setBlockSelected(blockId, true);

// After (v6)
import { Selection } from '@yoopta/editor';
Selection.setSelected(editor, { blockId });

​
Step 6: Update Event Handlers

Change event API: 
// Before (v4.9.x)
editor.on('change', (value: YooptaContentValue) => {
  setValue(value);
});

// After (v6)
editor.on('change', ({ value, operations }: YooptaEventChangePayload) => {
  setValue(value);
  console.log('Operations:', operations);
});
Better: Use onChange prop: 
<YooptaEditor
  editor={editor}
  onChange={(value) => setValue(value)}
/>

​
Step 7: Update Drag and Drop

If you use drag-and-drop, update the implementation: Before (v4.9.x): 
<YooptaEditor
  plugins={plugins}
  enableDragAndDrop
/>
After (v6): 
import { BlockDndContext, SortableBlock } from '@yoopta/ui';

<YooptaEditor
  editor={editor}
  renderBlock={(props) => <SortableBlock {...props} />}
>
  <BlockDndContext>
    {/* UI components */}
  </BlockDndContext>
</YooptaEditor>

​
Version-Specific Changes

​
6.0.1 (February 27, 2026)

Breaking: Removed --yoopta-shadcn-* prefix from CSS variables. Theme now reads standard shadcn variables directly.Migration:
/* Before */
--yoopta-shadcn-background: 0 0% 100%;
--yoopta-shadcn-foreground: 0 0% 3.9%;

/* After */
--background: 0 0% 100%;
--foreground: 0 0% 3.9%;
Action Required: If you have custom variables, rename them to match shadcn conventions.
Changed: Removed hardcoded maxWidth/maxHeight from embed, image, and video plugins. Default sizing now uses Infinity.Migration: If you relied on the old defaults, explicitly set size constraints:
import Image from '@yoopta/image';

const ImageWithMaxSize = Image.extend({
  options: {
    maxWidth: 1200,
    maxHeight: 800,
  },
});

​
6.0.0-beta.20 (February 12, 2026)

New: @yoopta/collaboration package for real-time collaborative editing.
npm install @yoopta/collaboration
See Collaboration docs for setup.

​
6.0.0-beta.19 (February 7, 2026)

New: Compound component for inline element configuration.
import { ElementOptions } from '@yoopta/ui';

<ElementOptions.Root>
  <ElementOptions.Trigger>Options</ElementOptions.Trigger>
  <ElementOptions.Content>
    <ElementOptions.ColorPicker label="Color" />
    <ElementOptions.Slider label="Size" />
  </ElementOptions.Content>
</ElementOptions.Root>

​
6.0.0-beta.21 (February 17, 2026)

Fixed: Focus loss when pressing Enter in lists (especially Safari).Action Required: None - automatic improvement.

​
4.9.9 → 6.0.0

Breaking: Removed unnecessary wrapper div from block render.Migration: Check your custom styles that target block wrappers:
/* Before - targeting wrapper */
.yoopta-block > div {
  /* styles */
}

/* After - target block directly */
.yoopta-block {
  /* styles */
}

​
Common Migration Issues

Cause: Using old API or not creating editor with createYooptaEditor.Fix:
// Ensure you're creating the editor instance
const editor = createYooptaEditor({ plugins, marks });
Cause: Forgot to render UI components as children.Fix:
<YooptaEditor editor={editor}>
  <FloatingToolbar />
  <ActionMenuList />
</YooptaEditor>
Cause: Not setting initial value correctly.Fix:
// Option 1: Pass to createYooptaEditor
const editor = createYooptaEditor({
  plugins: PLUGINS,
  marks: MARKS,
  value: initialValue,
});

// Option 2: Set in useEffect
useEffect(() => {
  editor.setEditorValue(initialValue);
}, []);
Cause: This was a bug in v4.9.x, fixed in v6.Fix: Upgrade to v6 - onChange no longer fires during initialization.
Cause: Missing CSS imports or using old variable names.Fix:
// Import theme styles
import '@yoopta/themes-shadcn/styles.css';
import '@yoopta/themes-shadcn/variables.css'; // if needed

​
Migration Checklist

  • Updated all packages to v6+
  • Uninstalled @yoopta/tools
  • Installed @yoopta/ui
  • Created editor with createYooptaEditor
  • Removed plugins, marks, and value from <YooptaEditor>
  • Updated UI components to be children
  • Updated onChange handler
  • Replaced deprecated API calls
  • Updated event handlers
  • Tested all functionality
  • Updated CSS styles if needed
  • Reviewed and updated custom plugins

​
Getting Help

If you encounter issues during migration:
  1. Check the examples in the repository
  2. Review the full changelog
  3. Ask in GitHub Discussions
  4. Report bugs in GitHub Issues

Getting Started

Fresh start with v6

Troubleshooting

Common issues and solutions

Build docs developers (and LLMs) love

Get started for freeTalk to us