How to Access and Integrate Custom Tools in the Unlayer Editor and React Applications

Unlayer provides flexible customization for its users, allowing the addition of custom tools to enhance functionality. This guide explains how to access these tools within the Unlayer editor and integrate them with the "react-email-editor" package in React-based projects.

Overview of Custom Tools in Unlayer

Custom tools in Unlayer allow developers to extend the functionality of the editor by introducing specific actions or content blocks. They can be configured to appear in the content panel and embedded in the editor interface.

The amount of custom tools allowed per plan is limited as well. However, you can always procure more custom tools as Add-Ons. Current limitations are as follows:

Legacy Plans:

Startup - 1 custom tool
Business - 2 custom tools
Growth - 5 custom tools

New Plans:

Launch - 1 custom tool
Scale - 3 custom tools
Optimize - 5 custom tools

Setting Up a Custom Tool in a React Application

To integrate a custom tool into Unlayer’s builder within a React application, follow the steps below:

1. Bundle Your Custom Tool

Use a module bundler like Webpack or Vite to bundle your custom tool code into a standalone JavaScript file. Organize your tool code in a dedicated directory for maintainability.

2. Host the Custom Tool

After bundling, upload the output JavaScript file to a publicly accessible URL (e.g., https://yourdomain.com/custom-tool.js).

3. Add customJS to Builder Configuration

Use the customJS option in the EmailEditor component to load your custom tool at runtime.

<EmailEditor
  ref={emailEditorRef}
  onReady={onReady}
  options={{
    projectId: 123456, // Replace with your actual Unlayer project ID
    displayMode: "email", // replace with "web", "document", or "popup"
    version: "latest",
    customJS: "https://yourdomain.com/custom-tool.js" // Replace with your actual custom JS file URL
  }}
/>

4. Custom Tool Code with JSX

Inside your custom tool script, you can use JSX for the viewer and exporter components.

If you want to import other components into the custom tool code, you can add JSX to the Unlayer’s viewer component.

For exporters, make sure to convert JSX to string using ReactDOMServer.renderToStaticMarkup(). Here is the code example for the same:

If you want to import other components into the custom tool code, you can add JSX to the Unlayer’s viewer component.
For exporters, make sure to convert JSX to string using ReactDOMServer.renderToStaticMarkup().

Example Code:

unlayer.registerTool({
  // ... your tool configuration here
  renderer: {
    Viewer: MyColorPicker, // this is your React component
    exporters: {
      web: function (values) {
        return ReactDOMServer.renderToStaticMarkup(
          <MyColorPicker />
        );
      },
      email: function (values) {
        return ReactDOMServer.renderToStaticMarkup(
          <MyColorPicker />
        );
      }
    },
    head: {
      css: function (values) {
        // Optional: return custom CSS as string
      },
      js: function (values) {
        // Optional: return custom JS as string
      }
    }
  }
});

Debugging Tips

My custom tool isn't showing. What should I check?

Use a complete script URL. When loading a JavaScript file through customJS, include http:// or https:// and the full path to the file. For example, use http://localhost:3000/tool.js, not localhost:3000/tool.js, //localhost:3000/tool.js, /tool.js, or ./tool.js. A file loading correctly in your application does not establish that it can load inside the editor.
Serve a built, standalone JavaScript bundle. Bundle your custom tool before passing its URL to customJS. Do not point the editor at an unbundled development entry point containing module import or export statements. Use a bundle compatible with a classic script, such as IIFE or UMD, that registers the tool through unlayer.registerTool().
Register the tool inside customJS. Call unlayer.registerTool() from the script loaded through customJS, not from your application's host page. The custom-tool registration methods are available in that editor context.
Check the request from the editor. Open browser developer tools and inspect the tool script request and console errors. Check that the request succeeds and returns the intended JavaScript, rather than an HTML fallback or an error page. If a local request fails, investigate browser security restrictions or HTTPS certificate problems before changing your tool implementation.
Check the project and plan. Confirm that the editor uses the intended projectId, that the project's plan supports Custom Tools, and that you have not exceeded its tool limit. If the script never runs, ask support to check the project's script-loading permissions as well.
Check the display mode. Your tool's supportedDisplayModes must include the mode you're using. The default is ['email', 'web'].
Try a simplified example. If the issue continues, share a minimal reproduction, the exact customJS URL, the projectId, your browser version, and any request or console errors with support.

How can I test without loading the file directly from localhost?

Host the built JavaScript bundle at a publicly accessible HTTPS URL and pass that complete URL through customJS. An HTTPS tunnel to your local server is another option to test.

A tunnel changes how the file is reached; it does not change the JavaScript the server returns. You still need a standalone bundle compatible with a classic script. It also does not change the project's plan permissions or Custom Tools limit.

Do I need to allow localhost?

No. localhost is allowed by default in the project's allowed-domain settings. See How and where should I add my allowed domain(s)?.

Allowed-domain settings and the browser's ability to load a tool script are separate checks. Allowing localhost does not by itself resolve a malformed script URL, a script-format problem, or a blocked request.

The tool appears in the editor but is missing from exports

Check that the tool's JavaScript file is publicly accessible and that the registration defines exporters for the display modes you use. See Custom Tool Renders as “Missing”.

Conclusion

By following these steps, you can efficiently access, configure, and integrate custom tools in both the Unlayer editor and React applications. If you encounter specific issues, verify the setup details and ensure configurations are aligned with Unlayer’s API and editor options.

We also have a Live Example of how to create a custom tool in React application.

How can I access and integrate custom tools in the Unlayer editor and React applications?