react-email-editor

repository·master·Indexed 26 days ago

https://github.com/unlayer/react-email-editor

A React wrapper for the Unlayer drag-and-drop email editor, allowing developers to embed a full-featured email builder into their applications. It provides the EmailEditor component and EditorRef for accessing imperative methods such as loadDesign, saveDesign, and exportHtml. Version 2.0.0 requires React >= 16.8 and Node >= 18.

Tokens
1.9K
Snippets
2
Records
12
Agent score
89%

What's inside react-email-editor

  1. Upgrade from version 1.x to 2.x

    master

    Version 2.0 is a modernization release. While the component API remains unchanged, note the following requirements and changes:

    • Requirements: React >= 16.8 and Node >= 18.
    • Imports: Import only from the package root. Deep imports like react-email-editor/dist/... are no longer supported.
    • Browser Support: The published code is ES2019. If using legacy toolchains that cannot parse ES2019, you must transpile node_modules or stay on 1.x.
    • Lifecycle: Editors are now explicitly destroyed on unmount to prevent memory leaks.
  2. Use EmailEditor with Next.js and React Server Components

    master
    The EmailEditor component renders into the DOM and is client-only. However, the published bundle includes the 'use client' directive, allowing you to import it directly into any Next.js Client Component without needing next/dynamic.
  3. Basic usage of the EmailEditor component

    master

    To use the editor, import EmailEditor and use a useRef hook with the EditorRef type to access the underlying Unlayer instance. You can use the onReady prop to perform actions once the editor is loaded, such as loading a saved design.

    import React, { useRef } from 'react';
    import { createRoot } from 'react-dom/client';
    
    import EmailEditor, { EditorRef, EmailEditorProps } from 'react-email-editor';
    
    const App = (props) => {
      const emailEditorRef = useRef<EditorRef>(null);
    
      const exportHtml = () => {
        const unlayer = emailEditorRef.current?.editor;
    
        unlayer?.exportHtml((data) => {
          const { design, html } = data;
          console.log('exportHtml', html);
        });
      };
    
      const onReady: EmailEditorProps['onReady'] = (unlayer) => {
        // editor is ready
        // you can load your template here;
        // the design json can be obtained by calling
        // unlayer.loadDesign(callback) or unlayer.exportHtml(callback)
        // const templateJson = { DESIGN JSON GOES HERE };
        // unlayer.loadDesign(templateJson);
      };
    
      return (
        <div>
          <div>
            <button onClick={exportHtml}>Export HTML</button>
          </div>
    
          <EmailEditor ref={emailEditorRef} onReady={onReady} />
        </div>
      );
    };
    
    createRoot(document.getElementById('app')!).render(<App />);
  4. Access Unlayer methods via EditorRef

    master

    All Unlayer methods are available through the editor instance located at emailEditorRef.current.editor. Common methods include:

    methodparamsdescription
    loadDesignObject dataTakes the design JSON and loads it in the editor
    saveDesignFunction callbackReturns the design JSON in a callback function
    exportHtmlFunction callbackReturns the design HTML and JSON in a callback function
  5. Configure EmailEditor properties

    master

    The EmailEditor component accepts the following properties:

    PropertyTypeDescription
    editorIdStringHTML div id of the container where the editor will be embedded (optional)
    minHeightStringminimum height to initialize the editor with (default 500px)
    onLoadFunctioncalled when the editor instance is created
    onReadyFunctioncalled when the editor has finished loading
    optionsObjectoptions passed to the Unlayer editor instance (default {})
    styleObjectstyle object for the editor container (default {})
  6. Use the EmailEditor component

    master

    The EmailEditor component is the primary entry point for embedding the Unlayer email editor into a React application. It can be used with a ref to access the underlying UnlayerEditor instance for calling imperative methods.

    Key Props

    • onLoad: Callback function triggered when the editor instance is created.
    • onReady: Callback function triggered when the editor is fully loaded and ready for interaction.
    • scriptUrl: The URL of the Unlayer embed script.
    • minHeight: Minimum height of the editor container (defaults to 500).
    • style: CSS styles for the editor container.
    • editorId: A unique identifier for the editor instance. If not provided, one is generated automatically.
    • options: Configuration object for the editor (includes appearance, displayMode, locale, projectId, and tools).
    • displayMode: Sets the editor mode (e.g., 'email').
    • locale: Sets the editor language.
    • projectId: The Unlayer project ID.
    • tools: Custom tools to be included in the editor.
  7. Configure the EmailEditor component via EmailEditorProps

    master

    The EmailEditorProps interface defines the configuration options for the <EmailEditor /> component.

    Key props include:

    • editorId: A unique identifier for the editor instance.
    • minHeight: Sets the minimum height of the editor (number or string).
    • onLoad: Callback function triggered when the Unlayer script is loaded. Receives the UnlayerEditor instance.
    • onReady: Callback function triggered when the editor is fully ready for interaction. Receives the UnlayerEditor instance.
    • options: Configuration object for the Unlayer engine. Note that displayMode can be passed here. This object accepts UnlayerOptions (excluding displayMode which is handled via the specialized type).
    • scriptUrl: Custom URL for the Unlayer script.
    • style: Standard React CSSProperties for styling the editor container.

    Note on Deprecated Props: Avoid using appearance, displayMode, locale, projectId, or tools directly on the component. Instead, use the options prop to configure these settings.

  8. Import the EmailEditor component

    master

    The react-email-editor package provides the EmailEditor component as its primary entry point. You can import it using a named import or as the default export.

    Use the EmailEditor component to embed the Unlayer email editor into your React application.

  9. Access the editor instance via EditorRef

    master
    To interact with the Unlayer editor programmatically (e.g., to export HTML or load a design), you should use a React ref typed with EditorRef. The ref object contains an editor property which holds the UnlayerEditor instance or null if not yet initialized.