Table of contents

TOC

• ✨ Features
• 📦 Installation
• 🚀 Quick Start
  • Basic Editor
  • Advanced Usage with Plugins
  • Chat Input Component
  • Editor Kernel API
• 🔌 Available Plugins
  • Core Plugins
  • Content Plugins
  • Plugin Architecture
  • Plugin Features
• 📖 API Reference
  • Editor Kernel
  • Plugin System
• 🛠️ Development
  • Setup
  • Available Scripts
  • Debug Environment Variables
  • Project Architecture
• 🤝 Contributing
• 🔗 Links
  • More Products
  • Design Resources
  • Development Resources

✨ Features

• 🎯 Dual Architecture - Both kernel-based API and React components for maximum flexibility
• ⚛️ React-First - Built for React 19+ with modern hooks and patterns
• 🔌 Rich Plugin Ecosystem - 10+ built-in plugins for comprehensive content editing
• 💬 Chat Interface Ready - Pre-built chat input components with mention support
• ⌨️ Slash Commands - Intuitive / and @ triggered menus for quick content insertion
• 📝 Multiple Export Formats - JSON, Markdown, and plain text export capabilities
• 🎨 Customizable UI - Antd-styled components with flexible theming
• 🔗 File & Media Support - Native support for images, files, tables, and more
• 🎯 TypeScript Native - Built with TypeScript for excellent developer experience
• 📱 Modern Build System - Optimized with Vite, lobedocs, and comprehensive testing

📦 Installation

To install @lobehub/editor, run the following command:

$ bun add @lobehub/editor

$ pnpm add @lobehub/editor

🚀 Quick Start

Basic Editor

The simplest way to get started with a fully-featured editor:

import {
  INSERT_HEADING_COMMAND,
  ReactCodeblockPlugin,
  ReactImagePlugin,
  ReactLinkPlugin,
  ReactListPlugin,
} from '@lobehub/editor';
import { Editor, useEditor } from '@lobehub/editor/react';

export default function MyEditor() {
  const editor = useEditor();

  return (
    <Editor
      placeholder="Start typing..."
      editor={editor}
      plugins={[ReactListPlugin, ReactLinkPlugin, ReactImagePlugin, ReactCodeblockPlugin]}
      slashOption={{
        items: [
          {
            key: 'h1',
            label: 'Heading 1',
            onSelect: (editor) => {
              editor.dispatchCommand(INSERT_HEADING_COMMAND, { tag: 'h1' });
            },
          },
          // More slash commands...
        ],
      }}
      onChange={(editor) => {
        // Handle content changes
        const markdown = editor.getDocument('markdown');
        const json = editor.getDocument('json');
      }}
    />
  );
}

Advanced Usage with Plugins

Add more functionality with built-in plugins:

import {
  INSERT_FILE_COMMAND,
  INSERT_MENTION_COMMAND,
  INSERT_TABLE_COMMAND,
  ReactFilePlugin,
  ReactHRPlugin,
  ReactTablePlugin,
} from '@lobehub/editor';
import { Editor, useEditor } from '@lobehub/editor/react';

export default function AdvancedEditor() {
  const editor = useEditor();

  return (
    <Editor
      editor={editor}
      plugins={[
        ReactTablePlugin,
        ReactHRPlugin,
        Editor.withProps(ReactFilePlugin, {
          handleUpload: async (file) => {
            // Handle file upload
            return { url: await uploadFile(file) };
          },
        }),
      ]}
      mentionOption={{
        items: async (search) => [
          {
            key: 'user1',
            label: 'John Doe',
            onSelect: (editor) => {
              editor.dispatchCommand(INSERT_MENTION_COMMAND, {
                label: 'John Doe',
                extra: { userId: 1 },
              });
            },
          },
        ],
      }}
    />
  );
}

Chat Input Component

Pre-built component optimized for chat interfaces:

import { ChatInput } from '@lobehub/editor/react';

export default function ChatApp() {
  return (
    <ChatInput
      placeholder="Type a message..."
      onSend={(content) => {
        // Handle message send
        console.log('Message:', content);
      }}
      enabledFeatures={['mention', 'upload', 'codeblock']}
    />
  );
}

Editor Kernel API

For advanced use cases, access the underlying kernel directly:

import { IEditor, createEditor } from '@lobehub/editor';

// Create editor instance
const editor: IEditor = createEditor();

// Register plugins
editor.registerPlugin(SomePlugin, { config: 'value' });

// Interact with content
editor.setDocument('text', 'Hello world');
const content = editor.getDocument('json');

// Listen to events
editor.on('content-changed', (newContent) => {
  console.log('Content updated:', newContent);
});

// Execute commands
editor.dispatchCommand(INSERT_HEADING_COMMAND, { tag: 'h2' });

🔌 Available Plugins

Core Plugins

Content Plugins

Plugin Architecture

All plugins follow a dual-architecture design:

🧠 Kernel Layer (Framework-agnostic)

• Plugin Interface: Standardized plugin system with lifecycle management
• Service Container: Centralized service registration and dependency injection
• Command System: Event-driven command pattern for editor operations
• Node System: Custom node types with serialization and transformation
• Data Sources: Content management and format conversion (JSON, Markdown, Text)

⚛️ React Layer (React-specific)

• React Components: High-level components for easy integration
• Hook Integration: Custom hooks for editor state and functionality
• Event Handling: React-friendly event system and callbacks
• UI Components: Pre-built UI elements with theming support

Plugin Features

• ✅ Fully configurable with TypeScript-typed options
• ✅ Composable - use any combination together
• ✅ Extensible - create custom plugins using the same API
• ✅ Event-driven - react to user interactions and content changes
• ✅ Service-oriented - modular architecture with dependency injection
• ✅ Internationalization - Built-in i18n support where applicable
• ✅ Markdown integration - Shortcuts, import/export, custom transformers
• ✅ Theme system - Customizable styling and appearance
• ✅ Command pattern - Programmatic control and automation

📖 API Reference

Utility Hooks

// Get editor instance
const editor = useEditor();

// Helper for plugin configuration
const PluginWithConfig = Editor.withProps(ReactFilePlugin, {
  handleUpload: async (file) => ({ url: 'uploaded-url' }),
});

Editor Kernel

createEditor(): IEditor

Create a new editor kernel instance:

const editor = createEditor();

IEditor Interface

Core editor methods:

interface IEditor {
  // Content management
  setDocument(type: string, content: any): void;
  getDocument(type: string): any;

  // Plugin system
  registerPlugin<T>(plugin: Constructor<T>, config?: T): IEditor;
  registerPlugins(plugins: Plugin[]): IEditor;

  // Commands
  dispatchCommand<T>(command: LexicalCommand<T>, payload: T): boolean;

  // Events
  on<T>(event: string, listener: (data: T) => void): this;
  off<T>(event: string, listener: (data: T) => void): this;

  // Lifecycle
  focus(): void;
  blur(): void;
  destroy(): void;

  // Access
  getLexicalEditor(): LexicalEditor | null;
  getRootElement(): HTMLElement | null;
  requireService<T>(serviceId: ServiceID<T>): T | null;
}

Plugin System

Creating Custom Plugins

import { IEditorKernel, IEditorPlugin } from '@lobehub/editor';

class MyCustomPlugin implements IEditorPlugin {
  constructor(private config: MyPluginConfig) {}

  initialize(kernel: IEditorKernel) {
    // Register nodes, commands, transforms, etc.
    kernel.registerNode(MyCustomNode);
    kernel.registerCommand(MY_COMMAND, this.handleCommand);
  }

  destroy() {
    // Cleanup
  }
}

Available Commands

Common commands you can dispatch:

// Content insertion
INSERT_HEADING_COMMAND; // { tag: 'h1' | 'h2' | 'h3' }
INSERT_LINK_COMMAND; // { url: string, text?: string }
INSERT_IMAGE_COMMAND; // { src: string, alt?: string }
INSERT_TABLE_COMMAND; // { rows: number, columns: number }
INSERT_MENTION_COMMAND; // { label: string, extra?: any }
INSERT_FILE_COMMAND; // { file: File }
INSERT_HORIZONTAL_RULE_COMMAND;

// Text formatting
FORMAT_TEXT_COMMAND; // { format: 'bold' | 'italic' | 'underline' }
CLEAR_FORMAT_COMMAND;

🛠️ Development

Setup

You can use Github Codespaces for online development:

Or clone it for local development:

$ git clone https://github.com/lobehub/lobe-editor.git
$ cd lobe-editor
$ pnpm install
$ pnpm run dev

This starts the lobedocs development server with the live component playground. The local URL is printed in the terminal.

Available Scripts

Debug Environment Variables

LobeHub Editor includes comprehensive debug logging that can be controlled via environment variables:

Basic Debug Configuration

# Enable all LobeHub Editor debug output
DEBUG=lobe-editor:*

# Enable only important logs (recommended for development)
DEBUG=lobe-editor:*:info,lobe-editor:*:warn,lobe-editor:*:error

# Enable specific components
DEBUG=lobe-editor:kernel,lobe-editor:plugin:*

Available Debug Categories

Debug Levels

Development Usage

# Full debug during development
DEBUG=lobe-editor:*

# Only critical logs
DEBUG=lobe-editor:*:error,lobe-editor:*:warn
# Plugin debugging
DEBUG=lobe-editor:plugin:*
# Service debugging
DEBUG=lobe-editor:service:*

Project Architecture

lobe-editor/
├── src/
│   ├── editor-kernel/           # 🧠 Core editor logic
│   │   ├── kernel.ts           # Main editor class with plugin system
│   │   ├── data-source.ts      # Content management (JSON/Markdown/Text)
│   │   ├── service.ts          # Service container and dependency injection
│   │   ├── plugin/             # Plugin base classes and interfaces
│   │   ├── react/              # React integration layer
│   │   └── types.ts            # TypeScript interfaces
│   │
│   ├── plugins/                # 🔌 Feature plugins
│   │   ├── common/             # 🏗️ Foundation components
│   │   │   ├── plugin/         # Base editor plugin
│   │   │   ├── react/          # ReactEditor, ReactEditorContent, ReactPlainText
│   │   │   ├── data-source/    # Content data sources
│   │   │   └── utils/          # Common utilities
│   │   │
│   │   ├── markdown/           # 📝 Markdown processing engine
│   │   │   ├── plugin/         # Markdown transformation plugin
│   │   │   ├── service/        # Markdown shortcut service
│   │   │   ├── data-source/    # Markdown serialization
│   │   │   └── utils/          # Transformer utilities
│   │   │
│   │   ├── upload/             # 📤 Upload management system
│   │   │   ├── plugin/         # Upload handling plugin
│   │   │   ├── service/        # Upload service with priority system
│   │   │   └── utils/          # Upload utilities
│   │   │
│   │   ├── slash/              # ⚡ Slash commands (/, @)
│   │   │   ├── plugin/         # Slash detection plugin
│   │   │   ├── react/          # ReactSlashPlugin, ReactSlashOption
│   │   │   ├── service/        # Slash service with fuzzy search
│   │   │   └── utils/          # Search and trigger utilities
│   │   │
│   │   ├── mention/            # 👤 @mention system
│   │   │   ├── plugin/         # Mention plugin with decorators
│   │   │   ├── react/          # ReactMentionPlugin
│   │   │   ├── command/        # INSERT_MENTION_COMMAND
│   │   │   └── node/           # MentionNode with serialization
│   │   │
│   │   ├── codeblock/          # 🎨 Syntax highlighting
│   │   │   ├── plugin/         # Codeblock plugin with Shiki
│   │   │   ├── react/          # ReactCodeblockPlugin
│   │   │   ├── command/        # Language and color commands
│   │   │   └── utils/          # Language detection
│   │   │
│   │   ├── image/              # 🖼️ Image upload & display
│   │   │   ├── plugin/         # Image plugin with captions
│   │   │   ├── react/          # ReactImagePlugin
│   │   │   ├── command/        # INSERT_IMAGE_COMMAND
│   │   │   └── node/           # BaseImageNode, ImageNode
│   │   │
│   │   ├── table/              # 📊 Table support
│   │   │   ├── plugin/         # Table plugin with i18n
│   │   │   ├── react/          # ReactTablePlugin
│   │   │   ├── command/        # Table manipulation commands
│   │   │   ├── node/           # Enhanced TableNode
│   │   │   └── utils/          # Table operations
│   │   │
│   │   ├── file/               # 📎 File attachments
│   │   │   ├── plugin/         # File plugin with status tracking
│   │   │   ├── react/          # ReactFilePlugin
│   │   │   ├── command/        # INSERT_FILE_COMMAND
│   │   │   ├── node/           # FileNode with metadata
│   │   │   └── utils/          # File operations
│   │   │
│   │   ├── link/               # 🔗 Link management
│   │   │   ├── plugin/         # Link plugin with validation
│   │   │   ├── react/          # ReactLinkPlugin
│   │   │   ├── command/        # Link commands
│   │   │   └── utils/          # URL validation and detection
│   │   │
│   │   ├── list/               # 📋 Lists (ordered/unordered)
│   │   │   ├── plugin/         # List plugin with nesting
│   │   │   ├── react/          # ReactListPlugin
│   │   │   ├── command/        # List manipulation commands
│   │   │   └── utils/          # List operations
│   │   │
│   │   └── hr/                 # ➖ Horizontal rules
│   │       ├── plugin/         # HR plugin with styling
│   │       ├── react/          # ReactHRPlugin
│   │       ├── command/        # HR insertion commands
│   │       └── node/           # HorizontalRuleNode
│   │
│   ├── react/                  # ⚛️ High-level React components
│   │   ├── Editor/             # Main Editor component with plugins
│   │   ├── ChatInput/          # Chat interface component
│   │   ├── ChatInputActions/   # Chat action buttons
│   │   ├── ChatInputActionBar/ # Action bar layout
│   │   ├── SendButton/         # Send button with states
│   │   └── CodeLanguageSelect/ # Code language selector
│   │
│   └── index.ts                # Public API exports
│
├── docs/                       # 📚 Documentation source
├── docs.config.ts              # lobedocs site configuration
├── tests/                      # 🧪 Test files
└── vitest.config.ts            # Test configuration

The architecture follows a dual-layer design:

1. Kernel Layer (editor-kernel/) - Framework-agnostic core with plugin system
2. React Layer (react/ + plugins/*/react/) - React-specific implementations

Each plugin follows a consistent structure:

• plugin/ - Core plugin logic and node definitions
• react/ - React components and hooks (if applicable)
• command/ - Editor commands and handlers
• service/ - Services and business logic
• node/ - Custom Lexical nodes
• utils/ - Utility functions and helpers

This allows for maximum flexibility - you can use just the kernel for custom integrations, or the React components for rapid development.

🤝 Contributing

Contributions of all types are more than welcome, if you are interested in contributing code, feel free to check out our GitHub Issues to get stuck in to show us what you're made of.

🔗 Links

More Products

• 🤯 Lobe Chat - An open-source, extensible (Function Calling), high-performance chatbot framework. It supports one-click free deployment of your private ChatGPT/LLM web application.
• 🅰️ Lobe Theme - The modern theme for stable diffusion webui, exquisite interface design, highly customizable UI, and efficiency boosting features.
• 🧸 Lobe Vidol - Experience the magic of virtual idol creation with Lobe Vidol, enjoy the elegance of our Exquisite UI Design, dance along using MMD Dance Support, and engage in Smooth Conversations.

Design Resources

• 🍭 Lobe UI - An open-source UI component library for building AIGC web apps.
• 🥨 Lobe Icons - Popular AI / LLM Model Brand SVG Logo and Icon Collection.
• 📊 Lobe Charts - React modern charts components built on recharts

Development Resources

• 🎤 Lobe TTS - A high-quality & reliable TTS/STT library for Server and Browser
• 🌏 Lobe i18n - Automation ai tool for the i18n (internationalization) translation process.

More Resources

---

📝 License

Copyright © 2025 LobeHub.
This project is MIT licensed.