Skip to main content
BlockComponentBuilder is an abstract class used to create custom block components in AppFlowy Editor. It provides the foundation for building, validating, and rendering block types.

​
Overview

Every block type in AppFlowy Editor is backed by a BlockComponentBuilder. This builder is responsible for:
  • Creating the widget for the block
  • Validating block data
  • Defining block actions
  • Configuring block appearance

​
Class definition

abstract class BlockComponentBuilder with BlockComponentSelectable {
  BlockComponentBuilder({
    this.configuration = const BlockComponentConfiguration(),
  });

  BlockComponentValidate validate = (_) => true;
  BlockComponentWidget build(BlockComponentContext blockComponentContext);
  bool Function(Node node) showActions = (_) => false;
  BlockActionBuilder actionBuilder = (_, __) => const SizedBox.shrink();
  BlockActionTrailingBuilder actionTrailingBuilder = (_, __) => const SizedBox.shrink();
  BlockComponentConfiguration configuration = const BlockComponentConfiguration();
}
Source: lib/src/editor/editor_component/service/renderer/block_component_service.dart:27-50

​
Constructor

​
configuration
BlockComponentConfiguration
default:"const BlockComponentConfiguration()"
Configuration object for the block component, controlling padding, text styles, and placeholders.

​
Properties

​
validate
BlockComponentValidate
Function to validate whether a node is valid for this block type. Returns true if valid, false otherwise. Invalid nodes are displayed as placeholder widgets.
BlockComponentValidate validate = (node) {
  return node.type == 'my_block_type';
};
​
showActions
bool Function(Node)
Determines whether to show block actions (drag handle, add button, etc.) for a given node.
showActions = (node) => true; // Always show actions
​
actionBuilder
BlockActionBuilder
Builds the action widget that appears when hovering over or selecting a block.
actionBuilder = (context, state) {
  return IconButton(
    icon: Icon(Icons.more_horiz),
    onPressed: () {
      // Show action menu
    },
  );
};
​
actionTrailingBuilder
BlockActionTrailingBuilder
Builds trailing actions that appear after the main action.
​
configuration
BlockComponentConfiguration
Configuration object controlling the block’s appearance and behavior.

​
Methods

​
build()

Builds the widget for this block component. 
BlockComponentWidget build(BlockComponentContext blockComponentContext);
​
blockComponentContext
BlockComponentContext
required
Context containing the node, editor state, and other information needed to build the block.
Returns: BlockComponentWidget - The widget representing this block.

​
BlockComponentSelectable mixin

The BlockComponentSelectable mixin provides methods for selection handling:

​
start()

Returns the start position of the block component. 
Position start(Node node) => Position(path: node.path, offset: 0);
For text blocks, this is always offset 0.

​
end()

Returns the end position of the block component. 
Position end(Node node) => Position(
  path: node.path,
  offset: node.delta?.length ?? 0,
);
For text blocks, this is the length of the delta. Source: lib/src/editor/editor_component/service/renderer/block_component_service.dart:52-65

​
Creating a custom builder

Here’s an example of creating a custom block component builder: 
import 'package:appflowy_editor/appflowy_editor.dart';
import 'package:flutter/material.dart';

class CalloutBlockComponentBuilder extends BlockComponentBuilder {
  CalloutBlockComponentBuilder({
    super.configuration,
  });

  @override
  BlockComponentWidget build(BlockComponentContext blockComponentContext) {
    return CalloutBlockComponentWidget(
      key: blockComponentContext.node.key,
      node: blockComponentContext.node,
      configuration: configuration,
      showActions: showActions(blockComponentContext.node),
      actionBuilder: (context, state) => actionBuilder(blockComponentContext, state),
      editorState: blockComponentContext.buildContext.read<EditorState>(),
    );
  }

  @override
  BlockComponentValidate validate = (node) {
    return node.type == 'callout' &&
           node.attributes.containsKey('icon') &&
           node.delta != null;
  };
}

​
Standard block component builders

AppFlowy Editor provides a map of standard block component builders: 
final Map<String, BlockComponentBuilder> standardBlockComponentBuilderMap = {
  ParagraphBlockKeys.type: ParagraphBlockComponentBuilder(),
  HeadingBlockKeys.type: HeadingBlockComponentBuilder(),
  BulletedListBlockKeys.type: BulletedListBlockComponentBuilder(),
  NumberedListBlockKeys.type: NumberedListBlockComponentBuilder(),
  TodoListBlockKeys.type: TodoListBlockComponentBuilder(),
  QuoteBlockKeys.type: QuoteBlockComponentBuilder(),
  DividerBlockKeys.type: DividerBlockComponentBuilder(),
  ImageBlockKeys.type: ImageBlockComponentBuilder(),
  TableBlockKeys.type: TableBlockComponentBuilder(),
};

​
Registering custom builders

Register your custom builder with the editor: 
final customBuilders = {
  ...standardBlockComponentBuilderMap,
  'callout': CalloutBlockComponentBuilder(),
};

AppFlowyEditor(
  editorState: editorState,
  blockComponentBuilders: customBuilders,
)

​
Type definitions

​
BlockComponentValidate

typedef BlockComponentValidate = bool Function(Node node);
Function type for validating nodes.

​
BlockActionBuilder

typedef BlockActionBuilder = Widget Function(
  BlockComponentContext blockComponentContext,
  BlockComponentActionState state,
);
Function type for building block actions.

​
BlockActionTrailingBuilder

typedef BlockActionTrailingBuilder = Widget Function(
  BlockComponentContext blockComponentContext,
  BlockComponentActionState state,
);
Function type for building trailing block actions.

BlockComponentConfiguration

Configure block component appearance

Custom Blocks

Guide to creating custom block components

Build docs developers (and LLMs) love

Get started for freeTalk to us