Unlayer custom tool lets you add unique blocks or elements to your editor, giving your users a fully tailored content-building experience.
Key Takeaways
Custom tools extend the default functionality of the Unlayer editor to help you add your own unique features and UI.
You’ll need an Unlayer account (with the editor already embedded into your app) and some JavaScript skills to create and manage a custom tool.
Process: define tool config → register with unlayer.registerTool() → add customization options → set rendering logic.
Test locally before deploying to production.
Understanding Custom Tools in Unlayer
Unlayer custom tool is a developer‑defined block or element that extends the editor beyond its default capabilities.
Instead of relying only on pre‑built content blocks, you can create components that match your exact business logic, design system, or data source.
For example, you might create:
A product listing block that pulls live inventory data from your store
A testimonial carousel with custom animations
A branded call‑to‑action block that matches your style guide
These tools live alongside the built‑in blocks in the sidebar, making them feel like a native part of the editing experience.
Prerequisites for Creating and Integrating a Custom Tool in Unlayer
While the editor is no‑code for end users, creating an Unlayer custom tool requires developer-level work. You’ll be writing JavaScript code to register your tool, define how it appears in the editor, and control how users can customize it.
Before you start building, make sure you have the following:
JavaScript knowledge: Custom tools are registered using theunlayer.registerTool() method. You’ll need to understand functions, JSON structures, and DOM manipulation to define your tool’s configuration, properties, and rendering logic.
An active Unlayer account: You’ll need access to the Unlayer Embed SDK to integrate the editor into your environment. If your product already uses Unlayer, confirm you have admin access to make integration changes.
An embedded editor setup: Custom tools work inside the embedded Unlayer editor instance in your application. Set up and test the embed before you start developing.
Familiarity with Unlayer’s tool configuration: Each tool has a JSON schema defining its label, icon, category, and supported features. Knowing how these fields work will help you structure your tool effectively from the start.
Having these prerequisites in place ensures you can move straight into the build process without stopping to troubleshoot basic setup issues.
Step-by-Step Process to Create an Unlayer Custom Tool
This process will walk you through building an Unlayer custom tool from setup to deployment, so it’s ready to use in your editor.
Step 1: Embed the Unlayer editor
Before creating a custom tool, you must have the Unlayer editor embedded in your application. Without the embedded editor, your tool cannot load, render, or be tested.
Read: Integrating an Email/Page Builder in SaaS: A Quick Guide
Step 2: Define your tool’s identity
Give your tool the basic details Unlayer needs to display it in the editor:
Choose a unique name (no spaces, lowercase, underscores only).
Set a label that appears in the sidebar (this will be visible to the end-users, unlike a unique name).
Pick an icon using a Font Awesome class (e.g., fa-smile) or a URL to a custom image.
Decide which display modes to support (web, email, landing page, popup, or all).
Step 3: Fill in the options object
Decide what users can customize in your tool:
Group related settings in a section or a property group (commonly default).
Inside each group, add option fields with:
A label for display in the sidebar.
A defaultValue for when the tool is inserted.
A widget type (text, color_picker, image, etc.).
Leave it empty (options: {}) if you don’t need any editable settings yet.
Step 4: Fill in the values object
Add default content or settings that your renderer will use:
Provide text, colors, or images that appear when the tool is first added.
Keep it empty if your renderer doesn’t need defaults.
Step 5: Set up the renderer
Control how your tool appears and exports:
Use Viewer to render it inside the editor preview.
Add exporters for web and email HTML output.
Use head.css or head.js if your tool needs extra styling or scripts.
Step 6: Add a validator (optional)
Ensure your tool’s data is valid before saving or exporting:
Check required fields.
Return an array of error messages if something is wrong.
Return an empty array ([]) if all checks pass.
Step 7: Implement unlayer.registerTool()
Bring together the identity, options, values, renderer, and validator into a single unlayer.registerTool() call.
unlayer.registerTool({
name: 'my_tool',
label: 'My Tool',
icon: 'fa-smile',
supportedDisplayModes: ['web', 'email'],
options: {
colors: {
// Property Group
title: 'Colors', // Title for Property Group
position: 1, // Position of Property Group
collapsed: false, // Initial collapse state
options: {
textColor: {
// Property: textColor
label: 'Text Color', // Label for Property
defaultValue: '#FF0000',
widget: 'color_picker', // Property Editor Widget: color_picker
},
backgroundColor: {
// Property: backgroundColor
label: 'Background Color', // Label for Property
defaultValue: '#FF0000',
widget: 'color_picker', // Property Editor Widget: color_picker
},
},
},
},
values: {},
renderer: {
Viewer: unlayer.createViewer({
render(values) {
return `<div style="color: ${values.textColor}; background-color: ${values.backgroundColor};">I am a custom tool.</div>`;
},
}),
exporters: {
web: function (values) {
return `<div style="color: ${values.textColor}; background-color: ${values.backgroundColor};">I am a custom tool.</div>`;
},
email: function (values) {
return `<div style="color: ${values.textColor}; background-color: ${values.backgroundColor};">I am a custom tool.</div>`;
},
},
head: {
css: function (values) {},
js: function (values) {},
},
},
validator(data) {
const { defaultErrors, values } = data;
return [];
},
});Source: Create a Custom Tool
Step 8: Test and deploy
Open the embedded editor locally.
Verify the tool appears in the correct sidebar category.
Check the preview and export work for both web and email.
Confirm validation behaves as expected.
Once confirmed, move the registration code to your production Unlayer embed configuration.
Note: Test your tool by dragging it into the editor and checking Viewer output. Switch to preview to confirm exporters work. If you’ve added properties, verify changes apply in both the editor and final HTML.
11 Best Practices for Building Custom Tools in Unlayer
Follow these guidelines to make your Unlayer custom tool maintainable, scalable, and smooth for end‑users.
Keep callbacks lightweight: Functions like onExport or onDesignChange should run quickly and avoid blocking the editor. Heavy logic slows down the design experience.
Register tools only when needed: Load and register the Unlayer custom tool only if the current project requires it. Keep configurations declarative with clear names, labels, and icons.
Improve usability with custom property editors: Go beyond basic text inputs by adding color pickers, sliders, or conditional fields. This makes the tool more intuitive for non‑technical users.
Optimize asset handling: Minimize image, CSS, and JavaScript sizes for faster load times. Use Unlayer’s CDN for hosted assets, or ensure efficient uploads if self‑hosting.
Validate early and clearly: Use the validator() function to check required fields or invalid inputs. Surface issues in the Audit tab so users know exactly what to fix.
Pass required data via configuration: Instead of hardcoding values, provide all necessary data through the tool configuration at initialization. This keeps tools flexible and reusable.
Separate editor and export logic: Keep Viewer rendering (editor preview) separate from Exporters (HTML output). Provide robust, email‑compatible markup where needed.
Label and document all options: Name properties clearly, set helpful default values, and document what each field does so users understand how to customize the tool.
Test in all modes and environments: Check your tool in multiple modes such as, web, email, landing page, popup, and document.Also, make sure to test in real‑world templates to ensure compatibility.
Avoid dependency conflicts: If building with React, use Unlayer’s React plugin, instead of bundling your own to prevent version clashes.
Related: Troubleshooting Common Issues When Embedding Unlayer in React
Bundle and host securely: Host your tool’s JS and CSS in a secure location. Double‑check registration steps, especially if using frameworks like Angular.
Start Building Your Unlayer Custom Tool Today
Creating an Unlayer custom tool lets you go beyond the default editor blocks and build features that fit your product perfectly.
With the right setup, clean code, and the best practices outlined above, you can deliver a fast, reliable, and fully tailored editing experience for your users.
Whether you’re integrating in React, Angular, or Vue, Unlayer gives you the flexibility to extend your editor without building everything from scratch.
Ready to create your own Unlayer custom tool?
Sign up or book a demo to start building and integrating your first tool today.
FAQs
1. Why isn’t my custom tool appearing in the Unlayer editor after registering it?
This usually happens when the tool's JavaScript isn’t correctly bundled, hosted at a public URL, or registered via the customJS property. Always ensure the JS file is publicly accessible and properly referenced in your Unlayer initialization configuration.
2. Why does my custom tool display as “Missing” or not export correctly to HTML, PDF, or image?
The most common causes are:
The custom tool’s JavaScript isn’t accessible from the export server (needs to be on a public, HTTPS URL)
Exporter functions weren’t defined for all targeted display modes (email, web, etc.) in your registerTool call.
3. What steps should I take to test and deploy a new Unlayer custom tool safely?
Thoroughly test your tool within the embedded Unlayer editor, verifying appearance, customization, and export functionality.
Once validated, update your production Unlayer configuration and review permissions (like domain whitelisting) to ensure seamless deployment.
4. What are the best practices for testing my custom tool across different frameworks (React, Angular, Vue)?
Frameworks handle lifecycles differently. Always register custom tools and initialize Unlayer after all dependencies and assets are loaded. Inspect console logs for registration or rendering errors.
Lastly, test in the Unlayer Developer Hub for independent verification.
5. How do I avoid issues with missing premium features or watermarks on my custom tool in production?
Production domains must be explicitly allowed (whitelisted) in your Unlayer Console, even if everything works on localhost. If features or your tool don’t show up in production, double-check the domain whitelist settings in Builder > Settings > Allowed Domains.