/react-email

React Email Editor Reference

A visual rich-text editor for building email templates, built on TipTap and ProseMirror. Embed it in your app to let users compose email-ready HTML without writing code.

Table of Contents

• Installation
• CSS Setup
• Architecture
• EmailEditor Component
• Minimal Setup (Extensions Only)
• Bubble Menus
• Slash Commands
• Inspector
• Email Theming
• Email Export
• Custom Extensions

Installation

Install the editor and its peer dependencies:

npm install @react-email/editor

Requires React 18+ and a bundler that supports package exports (Vite, Next.js, Webpack 5, etc.).

CSS Setup

Import the bundled default theme for the quickest start:

import '@react-email/editor/themes/default.css';

This includes the default color theme and built-in UI styles for bubble menus, slash commands, and the inspector.

To import only what you need:

import '@react-email/editor/styles/bubble-menu.css';
import '@react-email/editor/styles/slash-command.css';
import '@react-email/editor/styles/inspector.css';

Architecture

The editor is organized into six entry points:

EmailEditor Component

The EmailEditor component from @react-email/editor is a batteries-included component that bundles StarterKit, EmailTheming, BubbleMenus, and SlashCommands. Use it when you want the full experience with minimal setup.

import { EmailEditor, type EmailEditorRef } from '@react-email/editor';
import '@react-email/editor/themes/default.css';
import { useRef } from 'react';

export function MyEditor() {
  const editorRef = useRef<EmailEditorRef>(null);

  const handleExport = async () => {
    const { html, text } = await editorRef.current!.export();
    console.log(html, text);
  };

  return (
    <div>
      <EmailEditor
        ref={editorRef}
        content="<p>Start typing...</p>"
        theme="basic"
        onReady={(editor) => console.log('Editor ready', editor)}
        onChange={(editor) => console.log('Content changed')}
      />
      <button onClick={handleExport}>Export HTML</button>
    </div>
  );
}

Props

Ref Methods (EmailEditorRef)

Minimal Setup (Extensions Only)

For more control, use EditorProvider from @tiptap/react directly with StarterKit:

import { StarterKit } from '@react-email/editor/extensions';
import { EditorProvider } from '@tiptap/react';

const extensions = [StarterKit];

const content = {
  type: 'doc',
  content: [
    {
      type: 'paragraph',
      content: [{ type: 'text', text: 'Start typing or edit this text.' }],
    },
  ],
};

export function MyEditor() {
  return <EditorProvider extensions={extensions} content={content} />;
}

This gives you a content-editable area with all core extensions (paragraphs, headings, lists, tables, code blocks, columns, buttons, etc.) but no UI overlays.

Bubble Menus

Floating formatting toolbars that appear on text selection. Add as children of EditorProvider.

import { StarterKit } from '@react-email/editor/extensions';
import { BubbleMenu } from '@react-email/editor/ui';
import { EditorProvider } from '@tiptap/react';
import '@react-email/editor/themes/default.css';

const extensions = [StarterKit];

export function MyEditor() {
  return (
    <EditorProvider extensions={extensions} content={content}>
      <BubbleMenu />
    </EditorProvider>
  );
}

Available Bubble Menus

Exclude specific items from the default menu:

<BubbleMenu excludeItems={['strike', 'code', 'uppercase']} />

When combining the text bubble menu with contextual menus for links, images, or buttons, use hideWhenActiveMarks on BubbleMenu to prevent it from appearing when a link is focused.

Slash Commands

Insert content blocks by typing / in the editor.

import { defaultSlashCommands, SlashCommand } from '@react-email/editor/ui';

<EditorProvider extensions={extensions} content={content}>
  <SlashCommand items={defaultSlashCommands} />
</EditorProvider>

Default Commands

Cherry-pick individual commands:

import { BUTTON, H1, H2, TEXT } from '@react-email/editor/ui';

<SlashCommand items={[TEXT, H1, H2, BUTTON]} />

Inspector

A contextual sidebar for editing document-level styles, node properties, and text formatting. Requires the EmailTheming plugin.

import { StarterKit } from '@react-email/editor/extensions';
import { EmailTheming } from '@react-email/editor/plugins';
import { Inspector } from '@react-email/editor/ui';
import { EditorContent, EditorContext, useEditor } from '@tiptap/react';
import '@react-email/editor/themes/default.css';

const extensions = [StarterKit, EmailTheming];

export function MyEditor() {
  const editor = useEditor({ extensions, content });

  return (
    <EditorContext.Provider value={{ editor }}>
      <div style={{ display: 'flex' }}>
        <div style={{ flex: 1 }}>
          <EditorContent editor={editor} />
        </div>
        <Inspector.Root style={{ width: 240, borderLeft: '1px solid #e5e7eb', padding: 16 }}>
          <Inspector.Breadcrumb />
          <Inspector.Document />
          <Inspector.Node />
          <Inspector.Text />
        </Inspector.Root>
      </div>
    </EditorContext.Provider>
  );
}

The inspector automatically switches between document, node, and text controls based on the current selection.

Email Theming

Apply visual styles (typography, spacing, colors) to email output. Themes are resolved during composeReactEmail and inlined as style attributes.

import { StarterKit } from '@react-email/editor/extensions';
import { EmailTheming } from '@react-email/editor/plugins';

const extensions = [StarterKit, EmailTheming.configure({ theme: 'basic' })];

Built-in Themes

Switching Themes Dynamically

const [theme, setTheme] = useState<'basic' | 'minimal'>('basic');
const extensions = [StarterKit, EmailTheming.configure({ theme })];

// Re-key EditorProvider when theme changes
<EditorProvider key={theme} extensions={extensions} content={content}>

Email Export

Convert editor content to email-ready HTML and plain text.

Via EmailEditor ref

const editorRef = useRef<EmailEditorRef>(null);

const { html, text } = await editorRef.current!.export();

Via composeReactEmail (lower-level)

import { composeReactEmail } from '@react-email/editor/core';
import { useCurrentEditor } from '@tiptap/react';

function ExportPanel() {
  const { editor } = useCurrentEditor();

  const handleExport = async () => {
    if (!editor) return;
    const { html, text } = await composeReactEmail({
      editor,
      preview: 'Inbox preview text', // optional
    });
    console.log(html, text);
  };

  return <button onClick={handleExport}>Export HTML</button>;
}

The preview parameter is optional — when provided, it sets the inbox preview text in the exported HTML.

The export pipeline:

1. Reads the editor's JSON document
2. Traverses each node and mark
3. Calls renderToReactEmail() on each EmailNode and EmailMark
4. Applies theme styles via EmailTheming plugin (if configured)
5. Wraps in a base template and renders to HTML string + plain text

Custom Extensions

Create custom email-compatible nodes using EmailNode (extends TipTap's Node with renderToReactEmail()):

import { EmailNode } from '@react-email/editor/core';
import { mergeAttributes } from '@tiptap/core';

const Callout = EmailNode.create({
  name: 'callout',
  group: 'block',
  content: 'inline*',

  parseHTML() {
    return [{ tag: 'div[data-callout]' }];
  },

  renderHTML({ HTMLAttributes }) {
    return [
      'div',
      mergeAttributes(HTMLAttributes, {
        'data-callout': '',
        style: 'padding: 12px 16px; background: #f4f4f5; border-left: 3px solid #1c1c1c;',
      }),
      0,
    ];
  },

  renderToReactEmail({ children, style }) {
    return (
      <div style={{ ...style, padding: '12px 16px', backgroundColor: '#f4f4f5', borderLeft: '3px solid #1c1c1c' }}>
        {children}
      </div>
    );
  },
});

// Register it
const extensions = [StarterKit, Callout];

For custom marks (inline formatting), use EmailMark from @react-email/editor/core — same pattern but for inline elements.