Create Custom Tool & Property

Register a Custom Tool #

To integrate custom tools, utilize the customJS property. This property includes methods for registering tools and properties, such as registerTool and registerProperty.

Init Script #

mailui.init({
  customJS: [
    'https://example.com/custom-tools.js'
  ]
});

To add multiple custom tools, you can either use multiple customJS files or consolidate all tools into a single file for simplicity and ease of management.

Simple Example Script #

custom-tool.js

const { React, icons } = mailui; // or window.mailui

mailui.registerTool({
     name: "custom",
     label: "Custom Tool",
     icon: icons.IoRocketOutline, // or () => <span>🚀</span>,
     settings: {
         color: "#ff0", // "#8624E1",
         amp: false,
         badges: [{ label: "Pro" }],
         dropAccept: []
     },
     initialState: {
        content: "This is a Custom Tool"
     },
     toolbar: [
         {
             name: "group",
             label: "Custom Settings",
             isOpen: true,
             properties: [
                 {
                     name: "input",
                     label: "Custom Text",
                     path: "content",
                     formGroup: { className: "mb-6" },
                     responsive: false,
                     showLabel: true,
                     showDeviceSelectionMenu: true,
                 },
                 {
                     name: "range",
                     label: "Font Size",
                     path: "style.fontSize",
                     formGroup: { className: "mb-6" },
                     min: 0,
                     max: 20,
                     unit: "px",
                     responsive: true,
                     showLabel: true,
                     showDeviceSelectionMenu: true,
                 },
                 {
                     name: "color",
                     label: "Text Color",
                     path: "style.color",
                     formGroup: {},
                     responsive: true,
                     showLabel: true,
                     showDeviceSelectionMenu: true,
                 }
            ]
         }
     ],
     Edit: ({ state, children, attributes, styleElement }) => {
         return (
             <div>
                 {styleElement}
                 
                 <h4 {...attributes} style={{ ...attributes.style }}>
                    {state?.content}
                 </h4>
             </div>
         );
     },
     View: ({ state, children, attributes }) => {
         return (
             <div>
                 <h4 {...attributes} style={{ ...attributes.style }}>
                    {state?.content}
                 </h4>
             </div>
         );
     },
});

Configuration Options #

Certain configuration settings are needed to effectively use custom tools. The necessary options are outlined below.

Option	Required	Description	Type
name	Yes	Unique name for your tool	string
label	Yes	This is the label that users will see in the tools panel.	string
icon	Yes	The icon property can accept a React element `(e.g., CustomIcon)`, an inline component `(e.g., () => <div>Icon</div>)`, or a `react-icons/io5`component `(e.g., IoRocketOutline)`	ReactElement
settings	No	Settings contains tool customization options, like: color, amp, badges, dropAccept Settings Options	object
initialState	No	This is an object that defines the default values for this tool.	object
toolbar	yes	Toolbar is a array of properties and custom propertiesToolbar Options	array
Edit	yes	Component for editing the tool, allowing changes to state and appearance.Edit API	Component
View	yes	Component for viewing the tool, displaying its state and style.View API	Component

Settings Options #

Option	Required	Description	Type
color	No	The primary color for the tool.	string
amp	No	A boolean flag indicating if AMP (Accelerated Mobile Pages) is enabled.	string
badges	No	An array of badges or labels to display (e.g., [{ label: "Pro", variant: 'warning' }])	array
dropAccept	No	All available element tools and custom tools dropAccept allow you to make nested drag structure Available Tools	array

Edit / View API #

Prop	Description	Type
state	Entire object of this selected tool	object
attributes	All HTML data attrs	object
styleElement	The styleElement is an HTML `<style>` element used for embedding CSS styles.	object
children	React native children props `{ children }` This allow you to make nested drag structure	ReactNode

Register Custom Property #

custom-tool.js

...

mailui.registerProperty({
    name: "custom_property", // unique type name
    View: ({ value, state, setState, label }) => {
        return (
            <div>
                <label>{label}</label>
                <textarea
                    className="w-full"
                    value={value}
                    onChange={(event) => setState(event.target.value)}
                    rows="10"
                />
            </div>
        );
    }
});

Configuration Options #

Certain configuration settings are needed to effectively use custom property. The necessary options are outlined below.

Option	Required	Description	Type
name	Yes	Unique name for your property	string
View	Yes	Component for view the property, allowing changes to state and appearance.	Component

View API #

Prop	Description	Type
label	User provided label	string
value	User provided value	any
state	Entire object of this selected tool	object
setValue	Pass every time the value is changed	event
setState	The entire state can be updated with full flexibility using `setState`. A specific state property can be updated by passing an object structured as `{path: '', value: ''}`. Multiple state properties can be updated simultaneously by passing an array of such objects. `[ {path: '', value: ''}, {path: '', value: ''} ]` This approach ensures that state updates are managed efficiently and concisely.	event
[...]	You can access other API's provided with the toolbar.

Create Custom Tool & Property

Register a Custom Tool #

Init Script #

Simple Example Script #

Configuration Options #

Settings Options #

Edit / View API #

Register Custom Property #

Configuration Options #

View API #

Explore Our Email Builder