Editor Theming & Inspector

Relevant source files

The following files were used as context for generating this wiki page:

• packages/editor/src/plugins/email-theming/extension.spec.ts
• packages/editor/src/ui/inspector/text.tsx
• packages/editor/src/ui/inspector/root.spec.ts
• skills/react-email/references/EDITOR.md
• apps/web/src/app/editor/full-email-builder/example.tsx
• packages/editor/src/core/serializer/compose-react-email.spec.tsx
• packages/editor/src/plugins/email-theming/themes.ts
• packages/editor/src/ui/themes/default.css
• packages/editor/src/ui/inspector/inspector.css

The Editor Theming and Inspector systems provide the visual configuration layer for the React Email visual editor. Theming manages global and component-specific styles, while the Inspector provides a contextual user interface for modifying these styles and node attributes in real-time.

Together, these modules allow developers to embed a rich, customizable email creation experience within their applications. Theming ensures that the editor's visual output remains consistent with branding, while the Inspector enables users to adjust layout, typography, and element properties without writing code.
Sources: skills/react-email/references/EDITOR.md:1-12, apps/web/src/app/editor/full-email-builder/example.tsx:103-125

Email Theming System

The EmailTheming plugin handles the application of visual styles to email components. It supports built-in themes and custom configurations, injecting CSS into the editor's document head and ensuring these styles are preserved during serialization to email-ready HTML.

Theme Modes

The system provides two primary built-in themes:

Theme	Description
basic	Provides full styling including typography, spacing, borders, and visual hierarchy.
minimal	Offers a blank slate with essentially no styles, intended for custom branding.

Sources: skills/react-email/references/EDITOR.md:195-201, packages/editor/src/plugins/email-theming/extension.spec.ts:168-185

Style Injection Logic

When the EmailTheming plugin is configured, it performs the following actions:

1. Injects Default Styles: Adds CSS rules to the <head> of the browser document for editor nodes (e.g., .node-button, .node-list).
2. Scopes Styles: Restricts styles to the specific editor instance to prevent global CSS leakage.
3. Handles Global Content: Processes document-level styles like backgroundColor for the email body.
4. Serialization Support: Provides theme data to the composeReactEmail serializer, which inlines styles for email client compatibility.

The theming system synchronizes styles between the live editing environment and the final exported HTML.
Sources: packages/editor/src/plugins/email-theming/extension.spec.ts:143-162, skills/react-email/references/EDITOR.md:223-233

The Inspector Module

The Inspector is a contextual sidebar UI that allows users to edit properties of the selected node or the overall document. It is divided into logical sub-components that react to the current selection in the TipTap editor.

Inspector Components

The Inspector namespace includes several specialized components:

• Inspector.Root: The container that provides context and state for the sidebar.
• Inspector.Breadcrumb: Renders the hierarchy of nodes from the document root to the current selection.
• Inspector.Document: Controls for global email settings (e.g., background color, container width).
• Inspector.Node: Controls for the currently selected block node (e.g., padding, alignment, border).
• Inspector.Text: Controls for text-level formatting (e.g., bold, italic, links).

Sources: skills/react-email/references/EDITOR.md:162-181, apps/web/src/app/editor/full-email-builder/example.tsx:40-60

Selection and Path Resolution

The Inspector uses a path resolution logic to determine the "breadcrumb" trail of the current selection. It prepends a synthetic "body" node to typical content hierarchies to ensure users can always navigate back to document-level settings.

The inspector resolves the node hierarchy to allow users to navigate between parent layout blocks and child elements.
Sources: packages/editor/src/ui/inspector/root.spec.ts:39-65, apps/web/src/app/editor/full-email-builder/example.tsx:43-70

Text and Mark Inspection

The InspectorText component specifically manages text formatting. It monitors the editor's active marks and block attributes to provide a synchronized editing interface.

Managed Text Properties:

1. Marks: Bold, Italic, Underline, Strike, and Code.
2. Alignment: Left, Center, Right, and Justify (applied to the parent block).
3. Links: Href and Color (resolves theme colors vs. inline overrides).
4. Typography: Merges theme defaults with specific inline styles.

Sources: packages/editor/src/ui/inspector/text.tsx:45-66, packages/editor/src/ui/inspector/text.tsx:103-125

Style Merging and Conflict Resolution

The theming engine must resolve styles from multiple sources before rendering. It follows a specific priority order:

1. User Overrides: Styles explicitly set by the user in the Inspector (e.g., a specific link color).
2. Theme Config: Styles defined in the provided ThemeConfig object.
3. Default Theme: Fallback styles from the basic or minimal theme templates.

Conflict Resolution Table

Style Source	Priority	Logic
Inline Attribute	High	Overrides theme-level colors and padding.
Global Content	Medium	Document-wide styles like body background.
Theme Defaults	Low	Basic resets for nodes (e.g., line-height: 100%).

Sources: packages/editor/src/plugins/email-theming/extension.spec.ts:241-260, packages/editor/src/core/serializer/compose-react-email.spec.tsx:325-345, packages/editor/src/ui/inspector/text.tsx:90-100

Integration with Export Serialization

The theming and inspector settings are critical during the export process. When composeReactEmail is called, it traverses the Editor's JSON content and applies the resolved styles to the final React Email components.

• Button Reset: Ensures box-sizing: border-box and display: inline-block are applied to anchors to maintain layout in Outlook.
• Image Handling: Forces max-width: 100% on images to prevent horizontal overflow in mobile clients.
• Dark Mode: Injects @media (prefers-color-scheme: dark) CSS into the email <head> if not in preview mode.

Sources: packages/editor/src/core/serializer/compose-react-email.spec.tsx:288-315, packages/editor/src/core/serializer/compose-react-email.spec.tsx:360-385, skills/react-email/references/EDITOR.md:215-221

Summary

Editor Theming & Inspector constitute the design system of the React Email visual editor. Theming provides the structural and aesthetic foundation through injectable CSS and configurable themes, while the Inspector acts as the bridge between user intent and the editor's internal state. By resolving styles contextual to the selection and ensuring these styles survive serialization, the system enables the creation of high-fidelity, client-compatible emails.