React Email Editor

https://github.com/unlayer/react-email-editor
Admin
React Email Editor is an official React component that lets developers embed Unlayer’s drag-and-drop...
Tokens:37,240
Snippets:199
Trust Score:8.8
License:MIT
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install react-email-editor via npm

Source: https://github.com/unlayer/react-email-editor/blob/master/README.md

Install the react-email-editor package from NPM. Requires React >= 16.8 and Node >= 18 for version 2.0.

```bash
npm install react-email-editor --save
```

--------------------------------

### Basic usage with exportHtml

Source: https://github.com/unlayer/react-email-editor/blob/master/_autodocs/api-reference/email-editor.md

Basic usage example showing a hidden editor ref and a button that exports HTML. The exportHtml method is called on the editor instance obtained from the ref.

```tsx
import React, { useRef } from 'react';
import EmailEditor, { EditorRef } from 'react-email-editor';

const App = () => {
  const emailEditorRef = useRef<EditorRef>(null);

  const exportHtml = () => {
    emailEditorRef.current?.editor?.exportHtml((data) => {
      console.log(data.html, data.design);
    });
  };

  return (
    <>
      <button onClick={exportHtml}>Export HTML</button>
      <EmailEditor ref={emailEditorRef} />
    </>
  );
};
```

--------------------------------

### Advanced usage with typed display mode and events

Source: https://github.com/unlayer/react-email-editor/blob/master/_autodocs/api-reference/email-editor.md

Advanced usage example with typed display mode, forwarded events, deprecated-prop fallbacks, and loading a design on ready. Uses JSONTemplate type and EmailEditorProps for event handlers.

```tsx
import React, { useRef } from 'react';
import EmailEditor, { EditorRef, EmailEditorProps } from 'react-email-editor';
import type { JSONTemplate } from '@unlayer/types';

const sample = { counters: {}, body: { rows: [], values: {} } } as JSONTemplate<'email'>;

const App = () => {
  const ref = useRef<EditorRef<'email'>>(null);

  const onReady: EmailEditorProps['onReady'] = (unlayer) => {
    // editor:ready — safe to load a design here
    unlayer.loadDesign(sample);
  };

  const onDesignUpdated: EmailEditorProps['onDesignUpdated'] = ({ type, changes }) => {
    console.log('design updated', type, changes);
  };

  return (
    <EmailEditor
      ref={ref}
      onReady={onReady}
      onDesignUpdated={onDesignUpdated}
      options={{
        displayMode: 'email',
        appearance: { theme: 'modern_light' },
        features: { undoRedo: true },
      }}
    />
  );
};
```

--------------------------------

### Event-forwarding contract: filtering on* props and adding event listeners

Source: https://github.com/unlayer/react-email-editor/blob/master/_autodocs/api-reference/email-editor-props.md

Shows how props starting with 'on' (except onLoad and onReady) are registered as event listeners on the editor instance. The listener name is the prop name verbatim.

```tsx
// src/EmailEditor.tsx:112-135
const methodProps = Object.keys(props).filter((propName) => /^on/.test(propName));
...
editor.addEventListener(methodProp, props[methodProp]);
```

--------------------------------

### Render EmailEditor and export HTML

Source: https://github.com/unlayer/react-email-editor/blob/master/README.md

Basic usage example: render the EmailEditor component, get the editor instance via a ref, and export the HTML using the exportHtml method. The onReady callback is where you can load a design JSON with unlayer.loadDesign.

```tsx
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)
    // or generated from React code with @unlayer/react-elements (renderToJson)
    // 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 />);
```

--------------------------------

### Basic usage: typed display mode with forwarded events

Source: https://github.com/unlayer/react-email-editor/blob/master/_autodocs/api-reference/email-editor-props.md

Basic example of using EmailEditor with a typed display mode ('email') and forwarded event callbacks. Uses the indexed props type to get exact callback payload types.

```tsx
import React, { useRef } from 'react';
import EmailEditor, { EditorRef, EmailEditorProps } from 'react-email-editor';

const App = () => {
  const ref = useRef<EditorRef<'email'>>(null);

  // Use the indexed props type to get exact callback payload types.
  const onReady: EmailEditorProps['onReady'] = (unlayer) => {
    unlayer.loadBlank();
  };

  const onDesignUpdated: EmailEditorProps<'email'>['onDesignUpdated'] = (data) => {
    console.log(data.type, data.item, data.changes);
  };

  return <EmailEditor ref={ref} onReady={onReady} onDesignUpdated={onDesignUpdated} />;
};
```

--------------------------------

### Extension registration: registerTool example

Source: https://github.com/unlayer/react-email-editor/blob/master/_autodocs/api-reference/unlayer-editor.md

Registers a custom tool with the editor using registerTool. The config includes type, slug, label, icon, options, and values. The options property is of type OptionGroupConfigMap.

```tsx
import React, { useRef } from 'react';
import EmailEditor, { EditorRef } from 'react-email-editor';

const App = () => {
  const ref = useRef<EditorRef>(null);

  const onLoad: EmailEditorProps['onLoad'] = (unlayer) => {
    unlayer.registerTool({
      type: 'custom',
      slug: 'my_widget',
      label: 'My Widget',
      icon: 'fa-star',
      options: {
        my_option: {
          title: 'My option',
        },
      },
      values: {},
    });
  };

  return <EmailEditor ref={ref} onLoad={onLoad} />;
};
```

--------------------------------

### EmailEditorProps

Source: https://github.com/unlayer/react-email-editor/blob/master/_autodocs/api-reference/email-editor-props.md

Documentation for the EmailEditorProps interface, including event forwarding and usage examples.

```APIDOC
## EmailEditorProps

### Description
Props for the `EmailEditor` component. Includes callbacks, options, and event forwarding.

### Properties
- `options` (object) - Optional - Configuration options for the editor, e.g. `displayMode`, `locale`, `appearance`.
- `onLoad` (function) - Optional - Callback when the editor loads.
- `onReady` (function) - Optional - Callback when the editor is ready. Receives the Unlayer instance.
- `onDesignLoad` (function) - Optional - Callback when a design is loaded.
- `onDesignUpdated` (function) - Optional - Callback when the design is updated. Receives data with `type`, `item`, `changes`.
- `onImageUpload` (function) - Optional - Callback for image upload.
- `[key: \`on${string}\`]` (function) - Optional - Any other event listener prop is forwarded to the editor instance.
- `displayMode` (string) - Optional - Deprecated top-level prop, merged into `options.displayMode` if not set.
- `locale` (string) - Optional - Deprecated top-level prop, merged into `options.locale` if not set.
- `appearance` (object) - Optional - Deprecated top-level prop, merged into `options.appearance` if not set.

### Usage Example
```tsx
import React, { useRef } from 'react';
import EmailEditor, { EditorRef, EmailEditorProps } from 'react-email-editor';

const App = () => {
  const ref = useRef<EditorRef<'email'>>(null);

  const onReady: EmailEditorProps['onReady'] = (unlayer) => {
    unlayer.loadBlank();
  };

  const onDesignUpdated: EmailEditorProps<'email'>['onDesignUpdated'] = (data) => {
    console.log(data.type, data.item, data.changes);
  };

  return <EmailEditor ref={ref} onReady={onReady} onDesignUpdated={onDesignUpdated} />;
};
```
```

--------------------------------

### init(config?: Config): void

Source: https://github.com/unlayer/react-email-editor/blob/master/_autodocs/api-reference/unlayer-editor.md

Initializes the editor with the given configuration. Missing options fall back to the constructed instance's config.

```APIDOC
## init(config?: Config): void

### Description
Initializes the editor with the given configuration. Missing options fall back to the constructed instance's config.

### Method
init

### Parameters
- **config** (Config) - Optional - Configuration object for the editor.

### Response
No return value.
```

--------------------------------

### constructor(config?: Config)

Source: https://github.com/unlayer/react-email-editor/blob/master/_autodocs/api-reference/unlayer-editor.md

Creates a new editor instance with an optional configuration.

```APIDOC
## constructor(config?: Config)

### Description
Creates a new editor instance with an optional configuration.

### Method
constructor

### Parameters
- **config** (Config) - Optional - Configuration object for the editor.

### Response
No return value.
```

--------------------------------

### loadEditor(config: Config): void

Source: https://github.com/unlayer/react-email-editor/blob/master/_autodocs/api-reference/unlayer-editor.md

Internal boot phase called by createEditor; not for direct use.

```APIDOC
## loadEditor(config: Config): void

### Description
Internal boot phase called by createEditor; not for direct use.

### Method
loadEditor

### Parameters
- **config** (Config) - Required - Configuration object for the editor.

### Response
No return value.
```

--------------------------------

### initEditor(config: Config): void

Source: https://github.com/unlayer/react-email-editor/blob/master/_autodocs/api-reference/unlayer-editor.md

Internal boot phase called by createEditor; not for direct use.

```APIDOC
## initEditor(config: Config): void

### Description
Internal boot phase called by createEditor; not for direct use.

### Method
initEditor

### Parameters
- **config** (Config) - Required - Configuration object for the editor.

### Response
No return value.
```

--------------------------------

### renderEditor(config: Config): void

Source: https://github.com/unlayer/react-email-editor/blob/master/_autodocs/api-reference/unlayer-editor.md

Internal boot phase called by createEditor; not for direct use.

```APIDOC
## renderEditor(config: Config): void

### Description
Internal boot phase called by createEditor; not for direct use.

### Method
renderEditor

### Parameters
- **config** (Config) - Required - Configuration object for the editor.

### Response
No return value.
```

--------------------------------

### unlayer.init(config)

Source: https://github.com/unlayer/react-email-editor/blob/master/_autodocs/api-reference/unlayer-embed.md

Initializes the global editor instance with the given configuration. This is an instance method inherited from EditorClass.

```APIDOC
## unlayer.init(config)

### Description
Initializes the global editor instance with the provided configuration. This method is available on the global `unlayer` object because `Embed` extends `EditorClass`.

### Method
init

### Signature
```ts
init(config: Config): void;
```

### Parameters
- **config** (Config) - Required - Full editor configuration object.

### Usage Example
```ts
unlayer.init({
  id: 'my-editor',
  displayMode: 'email',
  projectId: 12345,
  appearance: { theme: 'modern_light' },
});
```
```

--------------------------------

### loadScript(callback, scriptUrl?)

Source: https://github.com/unlayer/react-email-editor/blob/master/_autodocs/api-reference/load-script.md

Documentation for the loadScript function, including its signature, parameters, return value, and module state machine behavior.

```APIDOC
## loadScript(callback, scriptUrl?)

### Description
Loads the Unlayer embed script and invokes the provided callback once the embed is usable. The callback is queued and executed in FIFO order, and the function returns undefined. Failures are not thrown synchronously; instead, callbacks may never fire.

### Method
Function call

### Endpoint
N/A (JavaScript function)

### Parameters
#### Parameters
- **callback** (Function) - Required - Invoked once per queued call, in FIFO order, once the embed is usable.
- **scriptUrl** (string) - Optional - Default: `'https://editor.unlayer.com/embed.js?2'` - Exact URL (matched with `script.src.includes(scriptUrl)`) of the embed script.

### Returns
`undefined`

### Behavior
- If no script tag with matching URL exists on the page, a `<script src={scriptUrl}>` element is appended to `document.head`; the callback queue drains on its `onload`.
- If a script tag exists and the embed is ready (`loaded` or global `unlayer` already defined), queued callbacks run synchronously.
- If a script tag exists but the embed is not ready, a `load` listener is attached to the existing element; callbacks drain when it fires.

### Readiness
`loaded || typeof unlayer !== 'undefined'` — presence of the global `unlayer` object is the authoritative signal.
```

--------------------------------

### Direct usage of global unlayer (init, createEditor, loadDesign, exportHtml, destroy)

Source: https://github.com/unlayer/react-email-editor/blob/master/_autodocs/api-reference/unlayer-embed.md

Shows how to use the global `unlayer` object directly without the React component: initializing with `init`, creating an isolated editor with `createEditor`, and using instance methods.

```ts
// After loading https://editor.unlayer.com/embed.js?2
unlayer.init({
  id: 'my-editor',
  displayMode: 'email',
  projectId: 12345,
  appearance: { theme: 'modern_light' },
});

// Or create an isolated instance
const editor = unlayer.createEditor({
  id: 'another-editor',
  displayMode: 'web',
});
editor.loadDesign({ counters: {}, body: { rows: [], values: {} } });
editor.exportHtml(({ html }) => console.log(html));
editor.destroy();
```

--------------------------------

### exportLiveHtml(callback, options?)

Source: https://github.com/unlayer/react-email-editor/blob/master/_autodocs/api-reference/unlayer-editor.md

Exports the current design as live HTML. The options are the same as ExportHtmlOptions but without the 'live' property, as live behavior is implied.

```APIDOC
## exportLiveHtml(callback, options?)

### Description
Exports the current design as live HTML. The options are the same as ExportHtmlOptions but without the 'live' property, as live behavior is implied.

### Method
exportLiveHtml

### Signature
```ts
exportLiveHtml<TDisplayMode extends DisplayMode | undefined = TClassDisplayMode>(callback: (data: ExportHtmlResult<TDisplayMode>) => void, options?: ExportLiveHtmlOptions): void;
```

### Parameters
- **callback** (function) - Required - Receives `ExportHtmlResult`.
- **options** (ExportLiveHtmlOptions) - Optional - `Omit<ExportHtmlOptions, 'live'>`.

### Return
`void`
```

--------------------------------

### Extension API Methods

Source: https://github.com/unlayer/react-email-editor/blob/master/_autodocs/api-reference/unlayer-editor.md

Methods for registering custom tools, panels, widgets, and exporters in the Unlayer editor.

```APIDOC
## registerContainerExporter

### Description
Registers an exporter for a container type.

### Method
registerContainerExporter

### Parameters
- **name** (`Container`) - Required - The container type ('body' | 'row' | 'column' | 'content').
- **exporter** (`BodyContainerExporter | RowContainerExporter | ColumnContainerExporter | ContentContainerExporter | null | undefined`) - Required - The exporter function.

### Returns
`void`

## registerItemExporter

### Description
Registers an exporter for an item.

### Method
registerItemExporter

### Parameters
- **name** (`string`) - Required - The item name.
- **exporter** (`ItemExporter<Record<string, unknown>> | null | undefined`) - Required - The exporter function.

### Returns
`void`

## registerTool

### Description
Registers a custom tool.

### Method
registerTool

### Parameters
- **config** (`ToolConfigDefinition`) - Required - The tool configuration.

### Returns
`void`

## registerPropertyEditor

### Description
Registers a property editor.

### Method
registerPropertyEditor

### Parameters
- **config** (`PropertyEditorConfig`) - Required - The property editor configuration.

### Returns
`void`

## registerTab

### Description
Registers a tab.

### Method
registerTab

### Parameters
- **config** (`TabConfig`) - Required - The tab configuration.

### Returns
`void`

## createPanel

### Description
Creates a panel.

### Method
createPanel

### Parameters
- **config** (`PanelConfig`) - Required - The panel configuration.

### Returns
`void`

## createViewer

### Description
Creates a viewer.

### Method
createViewer

### Parameters
- **config** (`ViewerConfig`) - Required - The viewer configuration.

### Returns
`void`

## createWidget (generic)

### Description
Creates a widget with a schema and mount/render functions.

### Method
createWidget

### Parameters
- **config** (`{ schema: S; mount: WidgetMountFn<InferSchemaType<S>>; render: WidgetRenderFn<InferSchemaType<S>> }`) - Required - The widget configuration.

### Returns
`void`

## createWidget (non-generic)

### Description
Creates a widget with a generic configuration.

### Method
createWidget

### Parameters
- **config** (`WidgetConfig<Value>`) - Required - The widget configuration.

### Returns
`void`
```

--------------------------------

### Guard against null editor with exportHtml

Source: https://github.com/unlayer/react-email-editor/blob/master/_autodocs/api-reference/editor-ref.md

Guards against the null editor instance with an explicit check before calling exportHtml. Demonstrates the recommended pattern of checking for readiness.

```tsx
import React, { useRef } from 'react';
import EmailEditor, { EditorRef } from 'react-email-editor';

const App = () => {
  const ref = useRef<EditorRef<'email'>>(null);

  const exportHtml = () => {
    const editor = ref.current?.editor;
    if (!editor) {
      console.warn('Editor not ready yet');
      return;
    }
    editor.exportHtml(
      ({ html, design }) => console.log(html, design),
      { minify: true, cleanup: true }
    );
  };

  return (
    <>
      <button onClick={exportHtml}>Export HTML</button>
      <EmailEditor ref={ref} />
    </>
  );
};

```

--------------------------------

### Editor Instance Methods

Source: https://github.com/unlayer/react-email-editor/blob/master/_autodocs/api-reference/unlayer-editor.md

Common editor operations: load, export, and event listening.

```APIDOC
## loadDesign

### Description
Loads a design template into the editor.

### Method
loadDesign

### Parameters
- **template** (`JSONTemplate<'email'>`) - Required - The template to load.

### Returns
`void`

## exportHtml

### Description
Exports the current design as HTML.

### Method
exportHtml

### Parameters
- **callback** (`({ html, design }) => void`) - Required - Callback receiving the exported HTML and design.
- **options** (`{ cleanup: boolean; inlineStyles: boolean; minify: boolean }`) - Optional - Export options.

### Returns
`void`

## exportImage

### Description
Exports the current design as an image.

### Method
exportImage

### Parameters
- **callback** (`({ url, error }) => void`) - Required - Callback receiving the image URL or error.
- **options** (`{ width: number; fullPage: boolean }`) - Optional - Export options.

### Returns
`void`

## addEventListener

### Description
Adds an event listener for editor events.

### Method
addEventListener

### Parameters
- **event** (`string`) - Required - The event name (e.g., 'design:loaded').
- **callback** (`(data) => void`) - Required - The event handler.

### Returns
`void`
```

--------------------------------

### createEditor(config)

Source: https://github.com/unlayer/react-email-editor/blob/master/_autodocs/api-reference/unlayer-embed.md

Creates a new editor instance with the given configuration. Returns an EditorClass instance that can be used to interact with the editor.

```APIDOC
## createEditor(config)

### Description
Creates a new editor instance with the provided configuration. This is the primary method for initializing an editor when using the embed script directly.

### Method
createEditor

### Signature
```ts
createEditor<TDisplayMode extends DisplayMode | undefined = undefined>(config: Config): EditorClass<TDisplayMode>;
```

### Parameters
- **config** (Config) - Required - Full editor configuration object. See configuration.md for every field.

### Return Value
Returns a new `EditorClass<TDisplayMode>` instance. The generic type is inferred from `config.displayMode` when a display-mode-typed config is passed; otherwise defaults to `undefined`.

### Usage Example
```ts
const editor = unlayer.createEditor({
  id: 'my-editor',
  displayMode: 'email',
  projectId: 12345,
  appearance: { theme: 'modern_light' },
});
```
```

--------------------------------

### exportZip(callback, options?)

Source: https://github.com/unlayer/react-email-editor/blob/master/_autodocs/api-reference/unlayer-editor.md

Exports the current design as a ZIP archive. The callback receives an ExportFromApiResult object.

```APIDOC
## exportZip(callback, options?)

### Description
Exports the current design as a ZIP archive. The callback receives an ExportFromApiResult object.

### Method
exportZip

### Signature
```ts
exportZip<TDisplayMode extends DisplayMode | undefined = TClassDisplayMode>(callback: (data: ExportFromApiResult<TDisplayMode>) => void, options?: ExportZipFromApiOptions): void;
```

### Parameters
- **callback** (function) - Required - Receives `ExportFromApiResult` = `{ design, url: string | null, error?: string }`.
- **options** (ExportZipFromApiOptions) - Optional - Options: `{ mergeTags?, language? }`.

### Return
`void`

### Error Handling
Failures are reported via the `error` field on the result (no declared throw).
```

--------------------------------

### Unlayer Editor API Methods

Source: https://github.com/unlayer/react-email-editor/blob/master/_autodocs/api-reference/unlayer-editor.md

API methods for live state, preview, history, audit, and remote data loaders.

```APIDOC
## setDesignId

### Description
Sets the design ID for the editor.

### Method
setDesignId

### Parameters
- **id** (string | null) - Required - The design ID to set.

### Response
void

```

```APIDOC
## setDesignMode

### Description
Sets the design mode for the editor.

### Method
setDesignMode

### Parameters
- **designMode** (DesignMode | null) - Required - The design mode to set.

### Response
void

```

```APIDOC
## setDisplayMode

### Description
Sets the display mode for the editor.

### Method
setDisplayMode

### Parameters
- **displayMode** (DisplayMode) - Required - The display mode to set.

### Response
void

```

```APIDOC
## setLocale

### Description
Sets the locale for the editor.

### Method
setLocale

### Parameters
- **locale** (Locale | null) - Required - The locale to set.

### Response
void

```

```APIDOC
## setTextDirection

### Description
Sets the text direction for the editor.

### Method
setTextDirection

### Parameters
- **textDirection** (TextDirection | null) - Required - The text direction to set.

### Response
void

```

```APIDOC
## setTranslations

### Description
Sets the translations for the editor.

### Method
setTranslations

### Parameters
- **translations** (Translations) - Required - The translations to set.

### Response
void

```

```APIDOC
## setAppearance

### Description
Sets the appearance configuration for the editor.

### Method
setAppearance

### Parameters
- **appearance** (DeepPartial<AppearanceConfig>) - Required - The appearance configuration to set.

### Response
void

```

```APIDOC
## setTheme

### Description
Sets the theme for the editor.

### Method
setTheme

### Parameters
- **theme** (AppearanceConfig['theme']) - Required - The theme to set.

### Response
void

```

```APIDOC
## showPreview

### Description
Shows the preview with the specified device and resolution.

### Method
showPreview

### Parameters
- **payload** (object | Device) - Required - Either a device string ('desktop' | 'mobile' | 'tablet') or an object with device and resolution.
  - **device** (Device) - Optional - The device type.
  - **resolution** (number) - Optional - The resolution.

### Response
void

```

```APIDOC
## hidePreview

### Description
Hides the preview.

### Method
hidePreview

### Parameters
None

### Response
void

```

```APIDOC
## canUndo

### Description
Checks if undo is possible.

### Method
canUndo

### Parameters
- **callback** (function) - Required - Callback that receives a boolean result.

### Response
void

```

```APIDOC
## canRedo

### Description
Checks if redo is possible.

### Method
canRedo

### Parameters
- **callback** (function) - Required - Callback that receives a boolean result.

### Response
void

```

```APIDOC
## undo

### Description
Undoes the last action.

### Method
undo

### Parameters
None

### Response
void

```

```APIDOC
## redo

### Description
Redoes the last undone action.

### Method
redo

### Parameters
None

### Response
void

```

```APIDOC
## audit

### Description
Runs an accessibility/quality audit and returns the results.

### Method
audit

### Parameters
- **callback** (function) - Required - Callback that receives an object with status and errors.
  - **status** ('FAIL' | 'PASS') - The audit status.
  - **errors** (Audit[]) - The list of audit errors.

### Response
void

```

```APIDOC
## loadProject

### Description
Loads a project by its ID.

### Method
loadProject

### Parameters
- **projectId** (number) - Required - The project ID.

### Response
void

```

```APIDOC
## loadUser

### Description
Loads a user.

### Method
loadUser

### Parameters
- **user** (User) - Required - The user object.

### Response
void

```

```APIDOC
## loadTemplate

### Description
Loads a template by its ID.

### Method
loadTemplate

### Parameters
- **templateId** (number) - Required - The template ID.

### Response
void

```

```APIDOC
## loadStockTemplate

### Description
Loads a stock template by its ID.

### Method
loadStockTemplate

### Parameters
- **stockTemplateId** (string) - Required - The stock template ID.

### Response
void

```

```APIDOC
## setLinkTypes

### Description
Sets the link types.

### Method
setLinkTypes

### Parameters
- **linkTypes** (LinkTypes) - Required - The link types.

### Response
void

```

```APIDOC
## setLinkTypesSharedConfig

### Description
Sets the shared configuration for link types.

### Method
setLinkTypesSharedConfig

### Parameters
- **linkTypesSharedConfig** (LinkTypesSharedConfig | null) - Required - The shared configuration.

### Response
void

```

```APIDOC
## setMergeTags

### Description
Sets the merge tags.

### Method
setMergeTags

### Parameters
- **mergeTags** (MergeTags) - Required - The merge tags.

### Response
void

```

```APIDOC
## setSpecialLinks

### Description
Sets the special links.

### Method
setSpecialLinks

### Parameters
- **specialLinks** (SpecialLink[]) - Required - The special links.

### Response
void

```

```APIDOC
## setDisplayConditions

### Description
Sets the display conditions.

### Method
setDisplayConditions

### Parameters
- **displayConditions** (DisplayConditions) - Required - The display conditions.

### Response
void

```

```APIDOC
## setBodyValues

### Description
Sets body values for a specific body.

### Method
setBodyValues

### Parameters
- **bodyValues** (Partial<BodyValues>) - Required - The body values.
- **bodyId** (number) - Optional - The body ID.

### Response
void

```

```APIDOC
## setStyleGuide

### Description
Sets the style guide.

### Method
setStyleGuide

### Parameters
- **styleGuide** (StyleGuideConfig) - Required - The style guide configuration.

### Response
void

```

```APIDOC
## setDesignTagsConfig

### Description
Sets the design tags configuration.

### Method
setDesignTagsConfig

### Parameters
- **designTagsConfig** (DesignTagsConfig) - Required - The design tags configuration.

### Response
void

```

```APIDOC
## setMergeTagsConfig

### Description
Sets the merge tags configuration.

### Method
setMergeTagsConfig

### Parameters
- **mergeTagsConfig** (MergeTagsConfig) - Required - The merge tags configuration.

### Response
void

```

```APIDOC
## setColorPickerConfig

### Description
Sets the color picker configuration.

### Method
setColorPickerConfig

### Parameters
- **colorPickerConfig** (ColorPicker) - Required - The color picker configuration.

### Response
void

```

```APIDOC
## setCurrentLanguage

### Description
Sets the current language.

### Method
setCurrentLanguage

### Parameters
- **language** (string) - Required - The language code.

### Response
void

```

```APIDOC
## setLanguages

### Description
Sets the available languages.

### Method
setLanguages

### Parameters
- **languages** (Language[]) - Required - The list of languages.

### Response
void

```

--------------------------------

### exportPlainText(callback, options?)

Source: https://github.com/unlayer/react-email-editor/blob/master/_autodocs/api-reference/unlayer-editor.md

Exports the current design as plain text. The callback receives an object with the text and the design JSON.

```APIDOC
## exportPlainText(callback, options?)

### Description
Exports the current design as plain text. The callback receives an object with the text and the design JSON.

### Method
exportPlainText

### Signature
```ts
exportPlainText<TDisplayMode extends DisplayMode | undefined = TClassDisplayMode>(callback: (data: ExportPlainTextResult<TDisplayMode>) => void, options?: ExportPlainTextOptions): void;
```

### Parameters
- **callback** (function) - Required - Receives `{ text: string; design: JSONTemplate<TDisplayMode> }`.
- **options** (ExportPlainTextOptions) - Optional - Options: `{ ignoreLinks?, ignoreImages?, ignorePreheader?, mergeTags? }`.

### Return
`void`
```

--------------------------------

### Advanced usage: options-only configuration with deprecated fallback props

Source: https://github.com/unlayer/react-email-editor/blob/master/_autodocs/api-reference/email-editor-props.md

Shows two equivalent configurations: one using an options object and one using deprecated top-level props. Both produce the same merged options object, with top-level props merged only when options lacks the field.

```tsx
import React from 'react';
import EmailEditor from 'react-email-editor';

// Equivalent configurations:
// 1) Options object
<EmailEditor
  options={{
    displayMode: 'popup',
    locale: 'fr',
    appearance: { actionBar: { placement: 'bottom' } },
  }}
/>;

// 2) Deprecated top-level props (merged into options only when options lacks the field)
<EmailEditor displayMode="popup" locale="fr" appearance={{ actionBar: { placement: 'bottom' } }} />;
```

--------------------------------

### exportHtml(callback, options?)

Source: https://github.com/unlayer/react-email-editor/blob/master/_autodocs/api-reference/unlayer-editor.md

Exports the current design as HTML, AMP, chunks, and the design JSON. The callback receives an ExportHtmlResult object.

```APIDOC
## exportHtml(callback, options?)

### Description
Exports the current design as HTML, AMP, chunks, and the design JSON. The callback receives an ExportHtmlResult object.

### Method
exportHtml

### Signature
```ts
exportHtml<TDisplayMode extends DisplayMode | undefined = TClassDisplayMode>(callback: (data: ExportHtmlResult<TDisplayMode>) => void, options?: ExportHtmlOptions): void;
```

### Parameters
- **callback** (function) - Required - Receives `{ html, amp, chunks, design }`.
- **options** (ExportHtmlOptions) - Optional - See configuration.md#exporthtmloptions.

### Return
`void`

### Result Shape
```ts
export interface ExportHtmlResult<TDisplayMode extends DisplayMode | undefined = undefined> {
  html: string;
  amp: {
    enabled: boolean;
    format: 'AMP' | 'AMP4EMAIL';
    html: string | undefined;
    validation: {
      status: 'UNKNOWN' | 'PASS' | 'FAIL';
      errors: Array<{
        severity: 'UNKNOWN_SEVERITY' | 'ERROR' | 'WARNING';
        line: number; col: number; message: string;
        specUrl: string | null; code: string; params: string[];
      }>;
    };
  };
  chunks: ExportChunksResult;
  design: JSONTemplate<TDisplayMode>;
}
```
```

--------------------------------

### CallbackTypeMap

Source: https://github.com/unlayer/react-email-editor/blob/master/_autodocs/types.md

Documentation for the CallbackTypeMap interface, listing all event callback signatures.

```APIDOC
## CallbackTypeMap

### Description
Defines the callback signatures for events emitted by the email editor. Each key is an event name and the value is the callback function signature.

### Events

#### 'editor:ready'
- **Callback**: `() => void`
- **Description**: Fired when the editor is ready.

#### 'textEditor:ready'
- **Callback**: `() => void`
- **Description**: Fired when the text editor is ready.

#### 'design:loaded'
- **Callback**: `(data: { design: JSONTemplate<TDisplayMode> }) => void`
- **Description**: Fired when a design is loaded.

#### onDesignLoad (deprecated)
- **Callback**: `(data: { design: JSONTemplate<TDisplayMode> }) => void`
- **Description**: Deprecated, use 'design:loaded' instead.

#### 'design:updated'
- **Callback**: `(data: { type: string; item?: Record<string, any>; changes?: Record<string, any> }) => void`
- **Description**: Fired when the design is updated.

#### 'image:uploaded'
- **Callback**: `(data: { image: { url: string; width?: number; height?: number } }) => void`
- **Description**: Fired when an image is uploaded.

#### onImageUpload (deprecated)
- **Callback**: `(data: { image: { url: string; width?: number; height?: number } }) => void`
- **Description**: Deprecated, use 'image:uploaded' instead.

#### 'item:selected'
- **Callback**: `(data: { item: Record<string, any>; active: boolean }) => void`
- **Description**: Fired when an item is selected.

#### 'page:added'
- **Callback**: `(data: { page: Record<string, any> }) => void`
- **Description**: Fired when a page is added.

#### 'page:removed'
- **Callback**: `(data: { page: Record<string, any> }) => void`
- **Description**: Fired when a page is removed.

#### 'body:added'
- **Callback**: `(data: { body: Record<string, any> }) => void`
- **Description**: Fired when a body is added.

#### 'body:removed'
- **Callback**: `(data: { body: Record<string, any> }) => void`
- **Description**: Fired when a body is removed.

#### 'row:added'
- **Callback**: `(data: { row: Record<string, any> }) => void`
- **Description**: Fired when a row is added.

#### 'row:removed'
- **Callback**: `(data: { row: Record<string, any> }) => void`
- **Description**: Fired when a row is removed.

#### 'row:moved'
- **Callback**: `(data: { row: Record<string, any> }) => void`
- **Description**: Fired when a row is moved.

#### 'header:added'
- **Callback**: `(data: { header: Record<string, any> }) => void`
- **Description**: Fired when a header is added.

#### 'header:removed'
- **Callback**: `(data: { header: Record<string, any> }) => void`
- **Description**: Fired when a header is removed.

#### 'footer:added'
- **Callback**: `(data: { footer: Record<string, any> }) => void`
- **Description**: Fired when a footer is added.

#### 'footer:removed'
- **Callback**: `(data: { footer: Record<string, any> }) => void`
- **Description**: Fired when a footer is removed.

#### 'column:added'
- **Callback**: `(data: { column: Record<string, any> }) => void`
- **Description**: Fired when a column is added.

#### 'column:removed'
- **Callback**: `(data: { column: Record<string, any> }) => void`
- **Description**: Fired when a column is removed.

#### 'content:added'
- **Callback**: `(data: { content: Record<string, any> }) => void`
- **Description**: Fired when content is added.

#### 'content:removed'
- **Callback**: `(data: { content: Record<string, any> }) => void`
- **Description**: Fired when content is removed.

#### 'content:moved'
- **Callback**: `(data: { content: Record<string, any> }) => void`
- **Description**: Fired when content is moved.

#### image
- **Callback**: `(data: { accepted: File[]; attachments: File[] }, done: (result: { progress?: number; url?: string; width?: number; height?: number; id?: number | string; filename?: string; abort?: boolean; error?: boolean | string; }) => void) => void`
- **Description**: Handles image upload.

#### selectImage
- **Callback**: `(data: Record<string, any>, done: (result: { url: string; width?: number; height?: number; size?: number; id?: string | number; }) => void) => void`
- **Description**: Handles image selection.

#### displayCondition
- **Callback**: `(data: Record<string, any> & { context: CallbackContext }, done: (result: { type: string; label: string; description: string; before: string; after: string; } | null) => void) => void`
- **Description**: Handles display condition.

#### mergeTag
- **Callback**: `(data: { mergeTags: MergeTags; mergeTagGroup?: string; mergeTagRule?: string; context: CallbackContext }, done: (result: { name?: string; value: string }) => void) => void`
- **Description**: Handles merge tag.

#### mergeTagRule
- **Callback**: `(data: { mergeTags: MergeTags; mergeTagGroup?: string; mergeTagRule?: string; context: CallbackContext }, done: (result: { mergeTagGroup: string; mergeTagRule: string }) => void) => void`
- **Description**: Handles merge tag rule.

#### previewHtml
- **Callback**: `(data: { html: string }, done: (result: { html: string }) => void) => void`
- **Description**: Handles HTML preview.

#### fetchImage
- **Callback**: `(data: { url: string }, done: (result: { blob: Blob; url?: string }) => void) => void`
- **Description**: Fetches an image.

#### 'image:removed'
- **Callback**: `(params: { id: string | number; projectId?: number | null; userId?: string | number }, done: () => void) => void`
- **Description**: Fired when an image is removed.

#### itemAdded
- **Callback**: `(data: { item: Record<string, any> }, done: (result: any) => void) => void`
- **Description**: Fired when an item is added.

#### itemRemoved
- **Callback**: `(data: { item: Record<string, any> }, done: (result: boolean) => void) => void`
- **Description**: Fired when an item is removed.

#### itemMoved
- **Callback**: `(data: { item: Record<string, any> }, done: (result: any) => void) => void`
- **Description**: Fired when an item is moved.

#### 'block:added'
- **Callback**: `(data: Record<string, any>, done: (result: any) => void) => void`
- **Description**: Fired when a block is added.

#### 'block:modified'
- **Callback**: `(data: Record<string, any>, done: (result: any) => void) => void`
- **Description**: Fired when a block is modified.

#### 'block:removed'
- **Callback**: `(data: Record<string, any>, done: (result: any) => void) => void`
- **Description**: Fired when a block is removed.

#### 'ai:assistant:generate'
- **Callback**: `(requestParams: AIAssistantRequestParams, done: (result: AIAssistantGenerateResult) => void) => void`
- **Description**: Generates AI assistant content.

#### 'ai:assistant:abort'
- **Callback**: `(requestParams: AIAssistantRequestParams) => void`
- **Description**: Aborts AI assistant request.

#### 'ai:assistant:on:request'
- **Callback**: `(requestParams: AIAssistantRequestParams) => void`
- **Description**: Called when AI assistant request is made.

#### 'ai:assistant:on:stream'
- **Callback**: `(event: AIAssistantStreamEvent) => void`
- **Description**: Called when AI assistant streams data.

#### 'ai:assistant:on:success'
- **Callback**: `(data: AIAssistantEventContext & { responseId?: string; provider?: string; modelId?: string; attempt?: number; durationMs?: number; locale?: string | null; toolType?: string; usage?: AIAssistantUsage; design: object | null; }) => void`
- **Description**: Called when AI assistant request succeeds.

#### 'ai:assistant:on:error'
- **Callback**: `(data: AIAssistantEventContext & { name: string; message: string; statusCode?: number; usage?: AIAssistantUsage; provider?: string; modelId?: string; attempt?: number; durationMs?: number; locale?: string | null; }) => void`
- **Description**: Called when AI assistant request fails.

#### 'ai:assistant:on:cancel'
- **Callback**: `(data: AIAssistantEventContext & { reason?: AICopilotCancelReason | null; partialUsage?: AIAssistantUsage; provider?: string; modelId?: string; attempt?: number; }) => void`
- **Description**: Called when AI assistant request is cancelled.
```

--------------------------------

### ExportPlainTextOptions

Source: https://github.com/unlayer/react-email-editor/blob/master/_autodocs/configuration.md

Options for the exportPlainText method, controlling plain-text output.

```APIDOC
## ExportPlainTextOptions

### Description
Options for the exportPlainText method, controlling plain-text output.

### Fields
- **ignoreLinks** (boolean) - Optional - Ignore links
- **ignoreImages** (boolean) - Optional - Ignore images
- **ignorePreheader** (boolean) - Optional - Ignore preheader
- **mergeTags** (Record<string, string>) - Optional - Merge-tag values to render
```

--------------------------------

### exportPdf(callback, options?)

Source: https://github.com/unlayer/react-email-editor/blob/master/_autodocs/api-reference/unlayer-editor.md

Exports the current design as a PDF. The callback receives an ExportFromApiResult object.

```APIDOC
## exportPdf(callback, options?)

### Description
Exports the current design as a PDF. The callback receives an ExportFromApiResult object.

### Method
exportPdf

### Signature
```ts
exportPdf<TDisplayMode extends DisplayMode | undefined = TClassDisplayMode>(callback: (data: ExportFromApiResult<TDisplayMode>) => void, options?: ExportPdfFromApiOptions): void;
```

### Parameters
- **callback** (function) - Required - Receives `ExportFromApiResult` = `{ design, url: string | null, error?: string }`.
- **options** (ExportPdfFromApiOptions) - Optional - Options: `{ mergeTags?, language? }`.

### Return
`void`

### Error Handling
Failures are reported via the `error` field on the result (no declared throw).
```

--------------------------------

### exportImage(callback, options?)

Source: https://github.com/unlayer/react-email-editor/blob/master/_autodocs/api-reference/unlayer-editor.md

Exports the current design as an image. The image is server-rendered by Unlayer's API. The callback receives an ExportFromApiResult object.

```APIDOC
## exportImage(callback, options?)

### Description
Exports the current design as an image. The image is server-rendered by Unlayer's API. The callback receives an ExportFromApiResult object.

### Method
exportImage

### Signature
```ts
exportImage<TDisplayMode extends DisplayMode | undefined = TClassDisplayMode>(callback: (data: ExportFromApiResult<TDisplayMode>) => void, options?: ExportImageFromApiOptions): void;
```

### Parameters
- **callback** (function) - Required - Receives `ExportFromApiResult` = `{ design, url: string | null, error?: string }`.
- **options** (ExportImageFromApiOptions) - Optional - Options: `{ width?, height?, fullPage?, deviceScaleFactor?, mergeTags?, language? }`.

### Return
`void`

### Error Handling
Failures are reported via the `error` field on the result (no declared throw).
```

--------------------------------

### Error handling on instance method: exportImage and event listener

Source: https://github.com/unlayer/react-email-editor/blob/master/_autodocs/api-reference/unlayer-editor.md

Shows how to handle errors from exportImage by checking the error field in the callback, and how to listen for the 'design:loaded' event. The API reports failure without throwing.

```tsx
import React, { useRef } from 'react';
import EmailEditor, { EditorRef, EmailEditorProps } from 'react-email-editor';

const App = () => {
  const ref = useRef<EditorRef>(null);

  const onLoad: EmailEditorProps['onLoad'] = (unlayer) => {
    // Async work: export image, examine the error field on failure.
    unlayer.exportImage(
      ({ url, error }) => {
        if (error || !url) {
          console.error('Image export failed:', error);
          return;
        }
        console.log('image url', url);
      },
      { width: 600, fullPage: true }
    );

    // Error channel: any unrecoverable embed failure surfaces via events.
    unlayer.addEventListener('design:loaded', ({ design }) => {
      console.log('loaded design', design);
    });
  };

  return <EmailEditor ref={ref} onLoad={onLoad} />;
};
```