Custom menu items
Use Cases
- Create a shortcut for an action or a series of actions that the user repeatedly does.
- Create a button for custom behavior.
How to create custom menu items
The methods for adding custom menu items are in the UI Registry part of the editor API editor.ui.registry. The API has three methods for adding menu items:
editor.ui.registry.addMenuItem
(identifier, configuration)editor.ui.registry.addNestedMenuItem
(identifier, configuration)editor.ui.registry.addToggleMenuItem
(identifier, configuration)
The two arguments these methods take are:
identifier
- a unique name for the buttonconfiguration
- an object containing your configuration for that button.
Define the custom toolbar button with the setup
callback of the TinyMCE configuration to add it to the editor. This callback is invoked automatically for every initialized editor instance. Access to the UI registry API occurs when the callback receives a reference to the editor instance as its argument.
Example of adding a custom menu item
tinymce.init({
selector: '#editor',
menu: {
custom: { title: 'Custom Menu', items: 'undo redo myCustomMenuItem' }
},
menubar: 'file edit custom',
setup: (editor) => {
editor.ui.registry.addMenuItem('myCustomMenuItem', {
text: 'My Custom Menu Item',
onAction: () => alert('Menu item clicked')
});
}
});
Note: The identifier used to create the menu item must be included in the
menu
option in the TinyMCE configuration for it to be added to the menubar’s menus. It will not be added to the menubar’s menus ifmenu
is not configured correctly.
Types of menu items
There are three types of menu items in TinyMCE 5.0:
- Basic menu items
- Nested menu items
- Toggle menu items
Basic menu items
A basic menu item triggers its onAction
function when clicked.
Config options
Name | Value | Requirement | Description |
---|---|---|---|
text | string | optional | Text to display if no icon is found. |
icon | string | optional | Name of the icon to be displayed. Must correspond to an icon in the icon pack. |
value | string | optional | A value to associate with the menu item. |
disabled | boolean | optional | default: false - Represents the menu item’s state. When true, the menu item is unclickable. Toggled by the menu item’s API. |
onSetup | (api) => (api) => void | optional | default: () => () => {} - Function invoked when the menu item is rendered, each time its menu is opened. |
onAction | (api) => void | required | Function invoked when the menu item is clicked. |
API
Name | Value | Description |
---|---|---|
isDisabled | () => boolean | Checks if the menu item is disabled. |
setDisabled | (state: boolean) => void | Sets the menu item’s disabled state. |
Example
editor.ui.registry.addMenuItem('basicitem', {
text: 'My basic menu item',
onAction: () => alert('Menu item clicked')
});
Nested menu items
A nested menu item is a menu item with a submenu. Registering a submenu this way allows it to be reused in menubar menus and toolbar button menus without having to define the submenu twice. The submenu can contain any combination of basic menu items and toggle menu items.
Name | Value | Requirement | Description |
---|---|---|---|
text | string | optional | Text to display if no icon is found. |
icon | string | optional | Name of the icon to be displayed. Must correspond to an icon in the icon pack. |
value | string | optional | A value to associate with the menu item. |
onSetup | (api) => (api) => void | optional | default: () => () => {} - Function invoked when the menu item is rendered, each time its menu is opened. |
getSubmenuItems | () => string or MenuItem[] | required | Function invoked when the menu item is clicked to open its submenu. Must return either a space separated string of registered menu names or an array of basic, toggle or nested menu items specifications. |
API
Name | Value | Description |
---|---|---|
isDisabled | () => boolean | Checks if the menu item is disabled. |
setDisabled | (state: boolean) => void | Sets the menu item’s disabled state. |
Example
editor.ui.registry.addNestedMenuItem('nesteditem', {
text: 'My nested menu item',
getSubmenuItems: () => {
return [{
type: 'menuitem',
text: 'My submenu item',
onAction: alert('Submenu item clicked')
}];
}
});
Toggle menu items
A toggle menu item triggers its onAction
when clicked. It also has a concept of state. This means it can be toggled on
and off
. A toggle menu item gives the user visual feedback for its state through a checkmark that appears to the left of the menu item’s text when it is on
.
Config options
Name | Value | Requirement | Description |
---|---|---|---|
text | string | optional | Text to display if no icon is found. |
value | string | optional | A value to associate with the menu item. |
active | boolean | optional | Initial state value for the toggle menu item |
disabled | boolean | optional | default: false - Represents the menu item’s state. When true, the menu item is unclickable. Toggled by the menu item’s API. |
onSetup | (api) => (api) => void | optional | default: () => () => {} - Function invoked when the menu item is rendered, each time its menu is opened. |
onAction | (api) => void | required | Function invoked when the menu item is clicked. |
Note: Toggle menu items do not have icons.
API
Name | Value | Description |
---|---|---|
isActive | () => boolean | Checks if the menu item is active. |
setActive | (state: boolean) => void | Sets the menu item’s active state. |
isDisabled | () => boolean | Checks if the menu item is disabled. |
setDisabled | (state: boolean) => void | Sets the menu item’s disabled state. |
Example
// Menu items are recreated when the menu is closed and opened, so we need
// a variable to store the toggle menu item state.
var toggleState = false;
editor.ui.registry.addToggleMenuItem('toggleitem', {
text: 'My toggle menu item',
onAction: () => {
toggleState = !toggleState;
alert('Toggle menu item clicked');
},
onSetup: (api) => {
api.setActive(toggleState);
return () => {};
}
});