appflowy-editor: a block-based rich text editor for Flutter

A document made of blocks rather than a canvas of text

The AppFlowy Editor is described as a highly customizable rich-text editor for Flutter, and the project for AppFlowy and beyond. The library is published on pub.dev as `appflowy_editor` and is written in Dart.

The interesting word in the feature list is block. The list of customizable features names block components, such as form input controls, numbered lists and rich text widgets, alongside shortcut events, themes, the selection menu and the toolbar menu. A document is a sequence of block components rather than a single editable surface, and each block is a widget you can extend.

That is the design decision that makes the rest of the library's shape make sense. If the editor were one widget with a text field in it, there would be nothing to customise except colours. Because the document is composed of typed blocks, you can add a new kind of block, render it differently, and have it participate in the same selection, formatting and shortcut machinery as everything else. The README's example of the todo list block component demonstrates how to extend new styles based on existing rich text components, and the divider block component demonstrates how to extend a new block component and render it.

The other thing to note is who maintains it. The feature list credits ongoing maintenance by AppFlowy's core team and a community of more than 1,000 builders, and the tests are documented separately under a testing page. So this is not a side project: it is the editor component of the AppFlowy application, extracted into a package, with the reference implementations living in the AppFlowy repository itself.

The package version history shows the cadence. Releases are 6.1.0 from 2025-12-08, 5.2.0 from 2025-04-17 and 5.1.0 from 2025-03-17, and the last push to the repository was on 2026-08-06.

Getting started, and the one setup step that is easy to miss

The getting started path is the standard Flutter package flow, followed by creating an editor.

flutter pub add appflowy_editor
flutter pub get

To start using it, you create a new empty AppFlowyEditor object:

final editorState = EditorState.blank(withInitialText: true); // with an empty paragraph
final editor = AppFlowyEditor(
  editorState: editorState,
);

The editor is built from an `EditorState`, and the two ways to get one are the two ways you would expect. `EditorState.blank(withInitialText: true)` gives you a document with a single empty paragraph. Alternatively you can create an editor from a JSON object in order to configure your initial state:

final json = jsonDecode('YOUR INPUT JSON STRING');
final editorState = EditorState(document: Document.fromJson(json));
final editor = AppFlowyEditor(
  editorState: editorState,
);

There is also a documented path to create an editor from Markdown or Quill Delta, which the README links to an importing document. That matters more than it first appears, because it is the migration route for an app that already has documents in one of those formats, and it is a separate document from the rest of the documentation, which suggests it has some depth to it.

Then there is the step the README flags with a note: the parameters `localizationsDelegates` need to be assigned in the MaterialApp widget.

MaterialApp(
  localizationsDelegates: const [
    AppFlowyEditorLocalizations.delegate,
  ]，
);

This is the one piece of wiring that is easy to miss, because the editor widget itself looks complete without it. The delegate is what lets the editor render its own strings, so without it you get an editor whose built-in labels fall back to something unhelpful. It also means the editor is localisation-aware, which is consistent with the rest of the design being aimed at an application with a large international audience.

To see the editor working, the README points at the example in the repository, which is a full Flutter application with directories for android, ios, linux, macos, web and windows, plus a Firebase configuration and an integration_test directory.

Theming, block components and shortcut events are separate extension points

The customisation documentation is split into three areas, and separating them is the useful part of the structure.

Theming is the first, and it is the least deep. The README points at the documentation for customizing a theme, and at a real example in the AppFlowy repository itself, the editor_style.dart file in the document plugin, for how AppFlowy customises the theme. A theme is a set of colours and text styles applied to the editor's tokens, so the visual layer is replaceable without touching behaviour.

Block components are the second, and they are where the block model pays off. The examples given are the todo list block component, which demonstrates how to extend new styles based on existing rich text components, and the divider block component, which demonstrates how to extend a new block component and render it. The two examples are chosen to show the two directions of extension: reusing an existing block's behaviour with a new look, and adding a block type that did not exist. The README also links the editor page in the AppFlowy frontend as a further example of how the application itself uses these.

Shortcut events are the third. The example is the BIUS shortcut set, which demonstrates how to make text bold, italic, underline and strikethrough through shortcut keys, and the README points at the shortcuts directory for more. The characteristic of a shortcut system is that it is defined as data rather than as key handler code, so rebinding is a configuration change rather than a fork.

That three-way split, appearance, block behaviour and keyboard, is a coherent extension model. It also tells you what is not extensible in the same way. Anything that is a property of the document model itself, the structure of a paragraph or what counts as a selection, is fixed by the library rather than by you.

There is also a selection menu and a toolbar menu, both listed as customizable features, which is the third surface a user actually touches, alongside the text itself.

A dual licence and a versioned document model

Two things in the repository are worth knowing before you adopt the package, and neither is about the editor's features.

The first is the licence. All code contributed to the AppFlowy Editor project is dual-licensed and released under both the GNU Affero General Public License Version 3 and the Mozilla Public License, Version 2.0. The practical effect of a dual AGPL and MPL licence is that you can choose either, and the MPL is the permissive half. If you pick MPL 2.0, the file-level copyleft applies and modified files stay open while your larger application can be closed. The AGPL half is the stronger option and covers network use. Which one you take is a decision with legal weight, and the README points at the LICENSE file for the details.

The second is the document model. The README has a migration guide section pointing at an UPGRADING document, and the version numbers show why it exists. The releases go 5.1.0, 5.2.0, then 6.1.0, and a major version in a rich text editor is almost always a change to the document format or the block model rather than to the widgets. Since the package can import from JSON and from Markdown or Quill Delta, the document has a serialised form, and a serialised form that changes between major versions is a migration you have to plan for if you store documents.

That matters for a real application. If the editor is used to hold user data, the persistence layer has to track the editor's version, and a major upgrade is a data migration rather than a dependency bump.

The repository layout is consistent with a package rather than an application. There is `lib/`, `test/`, `example/`, `documentation/`, `assets/`, a `pubspec.yaml`, an `analysis_options.yaml` for the Dart analyzer, a `codecov.yml` and a `.fvmrc` pinning the Flutter version the project develops against. The `documentation/` directory holds the documents the README links to, including the testing page, the customising guide, the importing guide and the upgrading guide, so the prose documentation is versioned with the code.

The coverage badge points at codecov for the main branch, and the changelog is at the root, so the release history is maintained in the usual way.

Against building a document model and against a hosted editor SDK

The comparison worth making is with the two alternatives a Flutter team actually considers.

The first is building the editor yourself, which is what most teams do once and most teams regret. A text field with a formatting toolbar is a day of work. A text field that supports block types, selection across blocks, undo and redo across block boundaries, a selection menu that appears on selection, a toolbar, shortcuts, and a serialisable document that round-trips through JSON is a project of a different size. The AppFlowy Editor is that project, already done, with the extension points open.

What you give up is ownership of the model. The block taxonomy, what a selection means across blocks, and how undo interacts with block boundaries are the library's decisions, and the migration guide is the visible cost of those decisions changing.

The second alternative is a hosted editor SDK, from a company that sells a collaborative editor as a service. The trade there is different: you get a mature, collaborative document model and a back end, and you give up the fact that the documents live in your app and in your format. It is a bigger architectural commitment than adopting a Flutter package, and it is a sensible one if you want real time collaboration between users rather than a local editor.

The third option is a Flutter rich text package that is not block based, of the kind that renders markdown to a widget tree with a limited set of decorations. Those are smaller and simpler, and they are the right choice for a read-only or lightly editable document, for example an article view. What they cannot do is the thing this package is built for, which is a document where the user creates structured blocks and the app controls how each is rendered.

The honest summary is that appflowy-editor is for a Flutter application whose users write documents rather than read them, and where the app needs to control the look of every block. The customisation surface is the product, and the AGPL or MPL choice is the decision to make before you start.

Editorial conclusion

Adopt appflowy-editor if you are building a Flutter app that needs an editable document and want block-level control over rendering, theming and keyboard behaviour rather than a fixed editor widget. Do not adopt it if you want to ship a closed source product without reading the dual licence terms, because the code is released under both AGPL version 3 and MPL 2.0, and check first which version of the package your app's other dependencies allow, because the editor's document model and its shortcut system are opinionated and have changed across major versions.

Frequently asked questions

Official sources

1. AppFlowy-IO/appflowy-editor on GitHub
2. Issues
3. Project website
4. README
5. Releases