Visual Email Editor
Relevant source files
The following files were used as context for generating this wiki page:
The Visual Email Editor is a rich-text editing system for building and managing email templates. It uses TipTap and ProseMirror as its foundation to provide a modern editing experience that serializes directly to React Email components. The editor exports high-quality, email-ready HTML and plain text that works across major email clients.
Sources: README.md:65-67, EDITOR.md:1-4
System Architecture
The editor architecture uses a modular design split into six distinct entry points. This structure allows developers to import only the necessary modules for their specific use case.
| Import Entry Point | Purpose |
|---|---|
@react-email/editor | Provides the batteries-included EmailEditor component. |
@react-email/editor/core | Contains serialization logic, base node/mark classes, and event bus. |
@react-email/editor/extensions | Includes the StarterKit and over 35 email-specific extensions. |
@react-email/editor/ui | Contains user interface overlays like BubbleMenu, SlashCommand, and Inspector. |
@react-email/editor/plugins | Houses the EmailTheming system. |
@react-email/editor/utils | Provides helper functions for attributes and style manipulation. |
Sources: EDITOR.md:27-35, package.json:11-66
Component Relationship
The following diagram illustrates how the editor components interact with the TipTap core and the serialization engine.
The diagram shows the data flow from user interaction through internal representation to final email output.
Core Editor Component
The EmailEditor component provides a pre-configured editing environment. It bundles essential extensions and UI components to minimize setup requirements.
Key Ref Methods
When you use a ref with EmailEditor, it exposes methods to interact with the editor programmatically.
export(): Returns a Promise containing the finalizedhtmlandtext.getJSON(): Retrieves the current document state as TipTap JSON.getHTML(): Retrieves the raw HTML from the editor instance.
Sources: EDITOR.md:73-83, editor.tsx:50-60
Export Pipeline
The export pipeline converts the editor's internal state into a static email.
The sequence diagram details the internal steps taken when the application requests an export of the email content.
Sources: EDITOR.md:155-162, compose-react-email.spec.tsx:28-36
Content Extensions
The editor uses specialized extensions to ensure that rendered content remains compatible with email client limitations. These extensions extend TipTap's standard nodes with a renderToReactEmail() method.
StarterKit
The StarterKit registers basic formatting and layout blocks.
- Text Blocks: Headings (h1-h6), paragraphs, and lists.
- Layout Blocks: Sections, columns (2, 3, or 4), and dividers.
- Interactive Elements: Buttons and links with built-in style resets.
Sources: EDITOR.md:107-120, editor.tsx:90-180
Text Marks and Nesting
The serializer maintains strict nesting rules for marks (bold, italic, links) based on schema rank. Higher priority extensions, such as links, wrap around lower priority ones like bold text in the final DOM structure.
Sources: compose-react-email.spec.tsx:44-78
Theming and Style Resolution
The EmailTheming plugin manages visual consistency by applying typography, spacing, and color configurations to the email output.
Theme Modes
The system supports two primary built-in themes:
- Basic: Provides a full visual hierarchy with default typography and spacing.
- Minimal: Offers a blank slate with essentially no styles, useful for custom implementations.
Sources: EDITOR.md:131-137, extension.spec.ts:252-277
Inlining Logic
During export, the theme resolver performs the following actions:
- Resolves CSS properties based on the selected theme.
- Inlines styles directly into
styleattributes of HTML elements. - Ensures consistent behavior for specific nodes, such as adding
box-sizing: border-boxanddisplay: inline-blockto buttons.
Sources: extension.spec.ts:162-177, compose-react-email.spec.tsx:210-230
User Interface Elements
The editor includes several contextual UI overlays to assist with content creation.
- Bubble Menus: Floating toolbars that appear when selecting text, links, buttons, or images. Sources: EDITOR.md:89-105
- Slash Commands: A command menu triggered by typing
/, allowing users to insert new content blocks quickly. Sources: EDITOR.md:107-120, editor.tsx:173-180 - Inspector: A sidebar providing granular control over document-level styles and node-specific properties. Sources: EDITOR.md:122-129
The class diagram shows the composition of the EmailEditor and its primary UI sub-components.
Summary
The Visual Email Editor provides a robust framework for embedding email creation capabilities into applications. By combining TipTap's editing power with a custom React Email serialization pipeline, it bridges the gap between interactive editing and technical email compatibility. The modular entry points and extension system allow for significant customization while maintaining high standards for generated HTML and plain text output.