syncfusion-react-blockeditor

Syncfusion React Block Editor in React

Component Overview

The Syncfusion React BlockEditorComponent is a powerful block-based rich text editor that allows users to create, edit, and format content using a modern block architecture. Each piece of content (paragraphs, headings, lists, tables, code snippets) is a discrete, manageable block.

Key Capabilities

The BlockEditorComponent provides:

• Block-based architecture - Content structured as discrete, reorderable blocks
• Built-in block types - Paragraphs, headings, lists, tables, code, callouts, quotes, collapsible sections
• Intuitive menus - Slash commands, context menus, inline toolbars
• Drag-and-drop - Reorder blocks easily with visual handles
• Content export - Export as JSON, HTML, or plain text
• Accessibility - WCAG 2.1 compliant with keyboard navigation and screen reader support
• Customization - Custom styling, themes, RTL support, globalization
• Collaborative Editing - Real-time multi-user editing powered by Yjs, with user presence and remote cursors, document version history and snapshot management

Documentation Navigation Guide

Getting Started

📄 Read: references/getting-started.md

• Installation and npm package setup
• Basic component implementation
• CSS imports and theme configuration
• Creating your first block editor
• Setting initial content with blocks

Built-in Block Types

📄 Read: references/built-in-blocks.md

• Block type reference (Paragraph, Heading, List, Table, Code, Quote, Callout)
• Nested block types (CollapsibleHeading, CollapsibleParagraph)
• Block indentation and CSS class styling
• Content configuration and properties

Menus and Commands

📄 Read: references/block-editor-menus.md

• Slash command menu customization
• Context menu configuration with Table and Link options
• Inline toolbar setup with Transform, code, link, and color support
• Block action menu customization and tooltips
• Menu events and filtering

Drag-Drop and Content Management

📄 Read: references/drag-drop-and-content.md

• Drag-and-drop block reordering (enableDragAndDrop)
• Content insertion and nesting
• Drag events (blockDragStart, blockDragging, blockDropped)
• Programmatic block movement

Mentions and Labels

📄 Read: references/mentions-and-labels.md

• users prop and UserModel interface for @mention feature
• labelSettings prop and LabelItemModel interface for label feature
• ContentType.Mention / ContentType.Label inline content
• IMentionContentSettings / ILabelContentSettings

Methods and API

📄 Read: references/methods-and-api.md

• Block management methods (add, remove, update, move)
• Selection and cursor control
• Data export/import (JSON, HTML)
• Content formatting and rendering

Styling and Appearance

📄 Read: references/styling-and-appearance.md

• CSS theming and imports
• Theme customization with --sf CSS variables and Block Editor CSS classes/IDs
• Block styling with custom CSS classes
• Typography and formatting options
• Dark mode and responsive design
• Using Syncfusion Theme Studio for fully customized themes

Advanced Features

📄 Read: references/advanced-features.md

• Paste cleanup and content sanitization
• Undo/redo functionality
• Keyboard shortcut customization
• Read-only mode configuration
• XSS protection and HTML sanitization
• RTL support and internationalization

Collaborative Editing

📄 Read: references/collaborative-editing.md

• Quick Start guide: 6-step setup for real-time collaboration using y-websocket and WebSocket server
• Setting up a Vite React Block Editor, installing Yjs dependencies, and creating a WebSocket server on port 1234
• Creating a collaboration.ts configuration file with shared Yjs document, adapter, and provider
• Real-time collaborative editing powered by Yjs (CRDT-based sync and conflict resolution)
• Injecting the Collaboration and VersionHistory modules
• collaborationSettings property (provider, adapter, enableAwareness, versionHistory)
• Choosing a Yjs provider (y-websocket, y-webrtc, y-indexeddb, Hocuspocus, Liveblocks, PartyKit)
• User presence, remote cursors, and text selection overlays (enableAwareness)
• Configuring the current user via users and currentUserId
• Room-based collaboration with URL hash-based room management
• Version history: creating, listing, renaming, restoring, comparing, exporting, and importing snapshots
• Implementing custom snapshot storage via the IVersionStorage interface with IndexedDBVersionStorage
• Version history events: snapshotCreated, snapshotRestored

Accessibility

📄 Read: references/accessibility.md

• WCAG 2.1 compliance
• Keyboard navigation patterns
• Screen reader support and ARIA attributes
• Focus management
• Color contrast and visual indicators

Quick Start Example

import { BlockEditorComponent } from '@syncfusion/ej2-react-blockeditor';
import { BlockModel, ContentType } from '@syncfusion/ej2-react-blockeditor';
import '@syncfusion/ej2-react-blockeditor/styles/material.css';

function App() {
  // Define initial blocks
  const blocksData: BlockModel[] = [
    {
      id: 'block-1',
      blockType: 'Heading',
      properties: { level: 1 },
      content: [
        {
          contentType: ContentType.Text,
          content: 'Welcome to Block Editor'
        }
      ]
    },
    {
      id: 'block-2',
      blockType: 'Paragraph',
      content: [
        {
          contentType: ContentType.Text,
          content: 'This is your first paragraph. Click the "+" button to add more blocks.'
        }
      ]
    }
  ];

  return (
    <BlockEditorComponent
      id="block-editor"
      blocks={blocksData}
    />
  );
}

export default App;

Common Patterns

1. Add a Block Programmatically

const editorRef = React.useRef<BlockEditorComponent>(null);

const addNewBlock = () => {
  const newBlock: BlockModel = {
    blockType: 'Paragraph',
    content: [
      {
        contentType: ContentType.Text,
        content: 'New paragraph block'
      }
    ]
  };
  
  editorRef.current?.addBlock(newBlock);
};

2. Handle Menu Item Selection

const commandMenuSettings = {
  itemSelect: (args) => {
    console.log('Selected command:', args.command.label, args.command.id);
    // Handle custom actions based on selected command
  }
};

3. Export Content as JSON

const exportContent = () => {
  const jsonContent = editorRef.current?.getDataAsJson();
  console.log('Exported content:', jsonContent);
};

4. Enable Read-Only Mode

<BlockEditorComponent
  id="block-editor"
  blocks={blocksData}
  readOnly={true}
/>

Key Props

⚠️ Props toolbarSettings, containerCssClass, and showBlockHandle do not exist in the BlockEditor API and must not be used.

Prop	Type	Description
id	string	Unique identifier for the component
blocks	BlockModel[]	Array of block objects defining content
readOnly	boolean	Enable read-only mode (default: false)
width	string | number	Width of the editor container (default: '100%')
height	string | number	Height of the editor container
commandMenuSettings	CommandMenuSettingsModel	Customize slash command (/) menu
contextMenuSettings	ContextMenuSettingsModel	Configure right-click context menu
inlineToolbarSettings	InlineToolbarSettingsModel	Configure inline text selection toolbar
blockActionMenuSettings	BlockActionMenuSettingsModel	Configure block action (⋮) menu
transformSettings	TransformSettingsModel	Configure block type transform menu
imageBlockSettings	ImageBlockSettingsModel	Configure image upload and rendering
codeBlockSettings	CodeBlockSettingsModel	Configure code block languages
pasteCleanupSettings	PasteCleanupSettingsModel	Control paste sanitization behavior
users	UserModel[]	User list for @mention feature and collaboration presence with avatar colors
labelSettings	LabelSettingsModel	Label items and trigger char for label feature
enableDragAndDrop	boolean	Enable/disable drag-and-drop reordering (default: true)
undoRedoStack	number	Max number of undo/redo history steps
keyConfig	{ [key: string]: string }	Custom keyboard shortcut mappings
locale	string	Localization language code (default: 'en-US')
blockChanged	EmitType<BlockChangedEventArgs>	Fires when block content changes
collaborationSettings	CollaborationSettingsModel	Configure real-time collaboration with Yjs provider, awareness, and version history
currentUserId	string	Unique identifier of the current user for collaboration and cursor identification

Common Use Cases

Content Management System - Build a CMS with block-based editing, custom block types, and content export

Document Editor - Create a collaborative document editor with formatting, templates, and version control

Note-Taking App - Implement a personal notes app with nesting, tagging, and search capabilities

Blog Editor - Enable blog authors to write with rich formatting, media embeds, and preview

Knowledge Base - Build internal documentation with organized blocks, search, and linked references

Survey/Form Builder - Create dynamic surveys with conditional blocks and response capture

---