Skip to main content
This guide helps you migrate your AppFlowy Editor implementation between major versions.

​
Migration Overview

AppFlowy Editor follows semantic versioning. Major version updates may include breaking changes that require code modifications.
Version 6.0.0 introduced several new features:
  • Block wrapper support
  • Upgrade to Flutter 3.32.4
  • Performance improvements for auto-scrolling
  • Enhanced offline collaboration support
Version 5.0.0 brought significant improvements:
  • Text alignment support in text-based blocks
  • Deep copy functionality for nodes
  • Simple columns block support
  • Enhanced keyboard gesture support on mobile
  • Selection service interceptors for custom drag target nodes
Version 4.0.0 focused on drag and drop:
  • Block reordering via drag and drop
  • Auto-scroll when dragging to reorder
  • Moving blocks to become children of other blocks
  • Configurable auto-scroll edge offset
  • Multi-list indentation at once
Version 3.0.0 included:
  • Command improvements and shortcuts
  • Cursor height consistency fixes for Flutter 3.22
  • Content scrolling and jumping improvements
  • Enhanced markdown syntax handling
Version 2.0.0 marked the stable release:
  • Support for Flutter stable channel
  • Format style toggling with collapsed selection
  • Optimized mobile editing experience
  • Numbered list display in latin or roman format
  • Table plugin support (2.3.0+)

​
From 1.1 to 1.2

​
Breaking Changes

​
Constructor Changes

AppFlowyEditor.custom and AppFlowyEditor.standard have been removed. Use AppFlowyEditor constructor instead. Before: 
AppFlowyEditor.standard(
  editorState: editorState,
)
After: 
AppFlowyEditor(
  editorState: editorState,
  // blockComponentBuilders, characterShortcutEvents, and 
  // commandShortcutEvents now have default values if not customized
)

​
Class Renames

DefaultSelectable → DefaultSelectableMixin 
// Before
class MyComponent extends StatelessWidget with DefaultSelectable {
  // ...
}

// After
class MyComponent extends StatelessWidget with DefaultSelectableMixin {
  // ...
}
FlowyRichText → AppFlowyRichText 
// Before
FlowyRichText(
  node: node,
  textSpanDecorator: decorator,
)

// After
AppFlowyRichText(
  node: node,
  textSpanDecorator: decorator,
)

​
API Changes

TextSpanDecoratorForAttribute Context Parameter The TextSpanDecoratorForAttribute now requires a BuildContext parameter: 
// Before
TextSpan? decorateMethod(
  TextSpan textSpan,
  String? value,
) {
  // ...
}

// After
TextSpan? decorateMethod(
  BuildContext context,
  TextSpan textSpan,
  String? value,
) {
  // Can now use context for theme, localization, etc.
}

​
Version 2.0+ Updates

​
Flutter Version Requirements

Starting with version 2.0.0, AppFlowy Editor supports Flutter stable channel. Ensure your Flutter version meets the minimum requirements: 
flutter --version
# Should show Flutter 3.16.0 or higher

​
Mobile Platform Changes

Version 2.0+ includes significant mobile optimizations:
  • Enhanced touch gesture handling
  • Improved magnifier display
  • Better keyboard height observation
  • Optimized floating toolbar positioning
If you’ve customized mobile toolbar behavior, review your implementation against the new mobile editing APIs.

​
Version 3.0+ Updates

​
Table Support

Version 3.0+ introduces table plugin support. To use tables: 
import 'package:appflowy_editor/appflowy_editor.dart';

final blockComponentBuilders = {
  ...standardBlockComponentBuilderMap,
  TableBlockKeys.type: TableBlockComponentBuilder(),
};

​
Text Direction

Default text direction property added in version 3.2.0: 
AppFlowyEditor(
  editorState: editorState,
  textDirection: TextDirection.rtl, // or TextDirection.ltr
)

​
Version 4.0+ Updates

​
Drag and Drop

Version 4.0 introduces block drag-and-drop reordering: 
AppFlowyEditor(
  editorState: editorState,
  // Enable drag-to-reorder
  blockComponentBuilders: {
    ...standardBlockComponentBuilderMap,
  },
  // Customize auto-scroll edge offset
  autoScrollEdgeOffset: 100,
)

​
Keyboard Service Interceptor

New interceptor to prevent default operations: 
editorState.service.keyboardService?.interceptor = (event) {
  // Return true to prevent default operation
  return shouldInterceptEvent(event);
};

​
Version 5.0+ Updates

​
Text Alignment

Text alignment support in text-based blocks: 
final transaction = editorState.transaction
  ..updateNode(node, {
    'align': 'center', // 'left', 'center', 'right', 'justify'
  });
await editorState.apply(transaction);

​
Node Deep Copy

Deep copy functionality for nodes: 
final copiedNode = originalNode.copyWith(
  deepCopy: true,
);

​
Selection Interceptor

Customize drag target nodes: 
editorState.service.selectionService.interceptor = (node) {
  // Return modified node or null to use default
  return customDragTargetNode(node);
};

​
Version 6.0+ Updates

​
Block Wrapper Support

Version 6.0 introduces block wrapper for enhanced block customization: 
blockComponentBuilders: {
  'custom_block': BlockComponentBuilder(
    builder: (context) {
      return BlockWrapper(
        child: MyCustomBlock(),
      );
    },
  ),
}

​
Flutter 3.32.4

Upgrade your Flutter version to 3.32.4 or higher: 
flutter upgrade
flutter pub upgrade

​
Common Migration Issues

Problem: Cannot find 'DefaultSelectable' or similar errors.Solution: Check for renamed classes:
  • DefaultSelectable → DefaultSelectableMixin
  • FlowyRichText → AppFlowyRichText
Update your imports and class declarations accordingly.
Problem: Editor shows blank screen or crashes.Solution:
  1. Clear your build cache: flutter clean
  2. Update dependencies: flutter pub upgrade
  3. Check that you’re using the new AppFlowyEditor constructor
  4. Verify Flutter version compatibility
Problem: Custom text span decorators fail after upgrade.Solution: Add the BuildContext parameter to your decorator methods:
TextSpan? myDecorator(
  BuildContext context, // Add this
  TextSpan textSpan,
  String? value,
) {
  // Your decorator logic
}
Problem: Keyboard behavior changed on mobile after upgrade.Solution: Version 2.0+ includes refactored keyboard height observer. If you’ve customized keyboard behavior, update to use the new keyboard observer APIs:
editorState.service.keyboardService?.addListener(
  listener: myKeyboardListener,
);

​
Testing After Migration

After migrating, test these critical areas:
  1. Basic Editing: Type, delete, select text
  2. Formatting: Bold, italic, links, code blocks
  3. Block Operations: Create, delete, reorder blocks
  4. Mobile Gestures: Touch selection, toolbar display (if applicable)
  5. Undo/Redo: Verify history stack works correctly
  6. Custom Components: Test any custom block components
  7. Serialization: Test document save/load functionality

​
Getting Help

If you encounter migration issues:
  • Check the GitHub Issues
  • Review the changelog for detailed changes
  • Ask questions in the AppFlowy Discord community
  • Submit bug reports with migration context

​
Next Steps

Changelog

View detailed version history

Examples

Explore example applications

Build docs developers (and LLMs) love

Get started for freeTalk to us