Skip to main content

​
Introduction

Block components are the fundamental building blocks of AppFlowy Editor. Each block component represents a distinct type of content, from simple text paragraphs to complex tables. The block component system provides a flexible and extensible architecture for creating rich document structures.

​
Architecture

​
Core Components

The block component system consists of three main parts:
  1. BlockComponentBuilder - Factory class that creates block component widgets
  2. BlockComponentWidget - The stateful widget that renders the block
  3. Node - The data model that contains block attributes and content

​
Block Component Configuration

All block components share a common configuration system through BlockComponentConfiguration: 
const BlockComponentConfiguration(
  padding: EdgeInsets Function(Node node),
  indentPadding: EdgeInsets Function(Node node, TextDirection),
  placeholderText: String Function(Node node),
  textStyle: TextStyle Function(Node node, {TextSpan? textSpan}),
  placeholderTextStyle: TextStyle Function(Node node, {TextSpan? textSpan}),
  blockSelectionAreaMargin: EdgeInsets Function(Node node),
  textAlign: TextAlign Function(Node node),
)
Configuration Options:
  • padding - Vertical/horizontal padding for the block
  • indentPadding - Padding for nested/indented blocks
  • placeholderText - Text displayed when block is empty
  • textStyle - Text styling function
  • placeholderTextStyle - Styling for placeholder text
  • blockSelectionAreaMargin - Selection area margins
  • textAlign - Text alignment (start, center, end)

​
Available Block Types

Paragraph

Basic text block with rich text formatting

Heading

Headings from H1 to H6 with configurable styles

Bulleted List

Unordered lists with nested support

Numbered List

Ordered lists with automatic numbering

Quote

Block quotes with custom styling

Divider

Horizontal divider lines

Image

Resizable images with alignment

Table

Multi-cell tables with dynamic sizing

Custom Blocks

Create your own block components

​
Standard Block Components

AppFlowy Editor provides a complete set of standard block components through standardBlockComponentBuilderMap: 
final Map<String, BlockComponentBuilder> standardBlockComponentBuilderMap = {
  ParagraphBlockKeys.type: ParagraphBlockComponentBuilder(
    configuration: standardBlockComponentConfiguration.copyWith(
      placeholderText: (_) => 'Type / for commands',
    ),
  ),
  HeadingBlockKeys.type: HeadingBlockComponentBuilder(
    configuration: standardBlockComponentConfiguration,
  ),
  BulletedListBlockKeys.type: BulletedListBlockComponentBuilder(
    configuration: standardBlockComponentConfiguration,
  ),
  NumberedListBlockKeys.type: NumberedListBlockComponentBuilder(
    configuration: standardBlockComponentConfiguration,
  ),
  QuoteBlockKeys.type: QuoteBlockComponentBuilder(
    configuration: standardBlockComponentConfiguration,
  ),
  DividerBlockKeys.type: DividerBlockComponentBuilder(
    configuration: standardBlockComponentConfiguration,
  ),
  ImageBlockKeys.type: ImageBlockComponentBuilder(),
  TableBlockKeys.type: TableBlockComponentBuilder(),
  // ... and more
};

​
Key Concepts

​
Node Structure

Each block is represented by a Node with:
  • type - String identifier (e.g., ‘paragraph’, ‘heading’)
  • attributes - Map of block-specific data
  • children - List of child nodes for nesting

​
Delta Format

Text-based blocks use the Delta format for rich text content: 
Node paragraphNode({
  String? text,
  Delta? delta,
  Attributes? attributes,
}) {
  return Node(
    type: ParagraphBlockKeys.type,
    attributes: {
      ParagraphBlockKeys.delta: (delta ?? (Delta()..insert(text ?? ''))).toJson(),
      if (attributes != null) ...attributes,
    },
  );
}

​
Mixins for Common Functionality

Block components use mixins to share functionality:
  • SelectableMixin - Selection handling
  • DefaultSelectableMixin - Default selection behavior
  • BlockComponentConfigurable - Configuration access
  • BlockComponentBackgroundColorMixin - Background color support
  • BlockComponentTextDirectionMixin - Text direction (LTR/RTL)
  • BlockComponentAlignMixin - Alignment support
  • NestedBlockComponentStatefulWidgetMixin - Nested children support

​
Block Validation

Each block component implements a validation function: 
BlockComponentValidate get validate => (node) {
  // Return true if node is valid for this block type
  return node.delta != null;
};

​
Selection & Actions

Block components support:
  • Block Selection - Select entire blocks
  • Text Selection - Select text within blocks
  • Action Builders - Custom actions (drag handles, menus)
  • Remote Selection - Collaborative cursor display

​
Next Steps

Text Blocks

Learn about paragraph blocks and text formatting

Custom Blocks

Create your own custom block components

Build docs developers (and LLMs) love

Get started for freeTalk to us