---
title: "Creating custom Menu toolbar buttons"
description: "Creating custom Menu toolbar buttons for TinyMCE"
canonical_url: "https://www.tiny.cloud/docs/tinymce/latest/custom-menu-toolbar-button/"
md_url: "https://www.tiny.cloud/docs/tinymce/6/custom-menu-toolbar-button/index.md"
version: "6"
last_updated: "2023-04-14T00:45:15Z"
tokens: 2419
---
Important This page documents TinyMCE 6. For new projects, Tiny recommends using the latest, most up-to-date version. [See TinyMCE 8 documentation](../../latest/custom-menu-toolbar-button/).
# Creating custom Menu toolbar buttons
A toolbar menu button is a toolbar button that opens a menu when clicked. This menu can also contain submenus. This is useful for grouping together actions that would otherwise be several buttons on the toolbar. It can also be used to reduce visual clutter and save UI space, as menubar menu items and some toolbar buttons could be moved into a toolbar menu button. Potentially, all menubar menu items could be moved into toolbar menu buttons, allowing for the editor to be used without a menubar at all.
For example: The table plugin’s `table` toolbar button opens a menu similar to the menubar Table menu.
## Options
| Name | Value | Requirement | Description |
| --- | --- | --- | --- |
| fetch | `(success: (menu) => void, fetchContext) => void` | required | Function that takes a callback and a `fetchContext` object. The callback function must be passed the list of options for the button’s dropdown. The `fetchContext` object provides information which is useful for choosing which items should be passed to the callback. For more details on `fetchContext`, see [Searchable Menu Buttons](#searchable-menu-buttons) |
| 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](../editor-icon-identifiers/), in a [custom icon pack](../creating-an-icon-pack/), or added using the [`addIcon` API](../apis/tinymce.editor.ui.registry/#addIcon). |
| search | boolean or object | optional | If not false, adds a search field to the menu. For more details, see [Searchable Menu Buttons](#searchable-menu-buttons) |
| tooltip | string | optional | Text for button tooltip. |
| onSetup | `(api) => (api) => void` | optional | default: `() => () => {}` - Function that’s invoked when the button is rendered. For details, see: [Using `onSetup`](#using-onsetup). |
## API
| Name | Value | Description |
| --- | --- | --- |
| isEnabled | `() => boolean` | Checks if the button is enabled. |
| setEnabled | `(state: boolean) => void` | Sets the button’s enabled state. |
| NOTE: This feature is only available for TinyMCE 6.4 and later. | NOTE: This feature is only available for TinyMCE 6.4 and later. | NOTE: This feature is only available for TinyMCE 6.4 and later. |
| setText | `(text: string) => void` | Sets the text label to display. |
| setIcon | `(icon: string) => void` | Sets the icon of the button. |
## Menu button example and explanation
The following is a simple toolbar menu button example:
**Example**
```js
tinymce.init({
selector: 'textarea#custom-toolbar-menu-button',
height: 500,
toolbar: 'mybutton',
setup: (editor) => {
/* Menu items are recreated when the menu is closed and opened, so we need
a variable to store the toggle menu item state. */
let toggleState = false;
/* example, adding a toolbar menu button */
editor.ui.registry.addMenuButton('mybutton', {
text: 'My button',
fetch: (callback) => {
const items = [
{
type: 'menuitem',
text: 'Menu item 1',
onAction: () => editor.insertContent(' You clicked menu item 1!')
},
{
type: 'nestedmenuitem',
text: 'Menu item 2',
icon: 'user',
getSubmenuItems: () => [
{
type: 'menuitem',
text: 'Sub menu item 1',
icon: 'unlock',
onAction: () => editor.insertContent(' You clicked Sub menu item 1!')
},
{
type: 'menuitem',
text: 'Sub menu item 2',
icon: 'lock',
onAction: () => editor.insertContent(' You clicked Sub menu item 2!')
}
]
},
{
type: 'togglemenuitem',
text: 'Toggle menu item',
onAction: () => {
toggleState = !toggleState;
editor.insertContent(' You toggled a menuitem ' + (toggleState ? 'on' : 'off') + '');
},
onSetup: (api) => {
api.setActive(toggleState);
return () => {};
}
}
];
callback(items);
}
});
},
content_style: 'body { font-family:Helvetica,Arial,sans-serif; font-size:16px }'
});
```
This example configures a toolbar menu button with the label `My Button` that opens the specified menu when clicked. The top-level menu contains two items. The first menu item inserts content when clicked and the second menu item opens a submenu containing two menu items which insert content when clicked.
The `fetch` function is called when the toolbar menu button’s menu is opened. It is a function that takes a callback and passes it an array of menu items to be rendered in the drop-down menu. This allows for asynchronous fetching of the menu items.
## Searchable menu buttons
> **Note:** This feature is only available for TinyMCE 6.2 and later.
The button’s menu can be configured to have an input field for searching, as well as its usual items. The presence of the input field is controlled by the `search` field in the [options](#options). The `search` field can be a `boolean` or an `object` containing a single optional string `placeholder`. By default, `search` is false. If `search` is not false, the button’s menu will contain an input field with any specified placeholder text. As the user types into this field, the `fetch` function will be called with the text in the input field passed back as part of `fetchContext`. The `fetch` function is responsible for using this `fetchContext` to determine which items to pass to its `success` callback.
The `fetchContext` is an object containing a single string property: `pattern`. If the toolbar menu button has not configured `search` to be active, then the `pattern` string will be empty.
## Searchable menu button example and explanation
> **Note:** This feature is only available for TinyMCE 6.2 and later.
The following is a simple toolbar menu button example, where searching has been configured:
**Example**
```js
tinymce.init({
selector: 'textarea#custom-toolbar-menu-button-search',
height: 500,
toolbar: 'mybutton',
setup: (editor) => {
/* Menu items are recreated when the menu is closed and opened, so we need
a variable to store the toggle menu item state. */
let toggleState = false;
/* example, adding a toolbar menu button */
editor.ui.registry.addMenuButton('mybutton', {
text: 'My searchable button',
search: {
placeholder: 'Type...'
},
fetch: (callback, fetchContext) => {
if (fetchContext.pattern.length > 0) {
callback([
{
type: 'menuitem',
text: `You searched for: "${fetchContext.pattern}"`,
onAction: () => editor.insertContent(`Inserted selected search result`)
}
]);
} else {
const items = [
{
type: 'menuitem',
text: 'Menu item 1',
onAction: () => editor.insertContent(' You clicked menu item 1!')
},
{
type: 'togglemenuitem',
text: 'Toggle menu item',
onAction: () => {
toggleState = !toggleState;
editor.insertContent(' You toggled a menuitem ' + (toggleState ? 'on' : 'off') + '');
},
onSetup: (api) => {
api.setActive(toggleState);
return () => {};
}
}
];
callback(items);
}
}
});
},
content_style: 'body { font-family:Helvetica,Arial,sans-serif; font-size:16px }'
});
```
This example configures a toolbar menu button with the label `My searchable button` that opens the specified menu when clicked. The menu will contain a search input field because `search` is not `false`. The input field’s [placeholder attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#placeholder) will be `Type...`.
Initially, when the menu opens, the search input field will be empty, and the `fetch` function is called with an empty `pattern` for its `fetchContext`. In that situation, `fetch` passes back an array of two items to be rendered in the drop-down menu. When the user types in the input field, `fetch` will be called again, except this time, the `pattern` property in `fetchContext` will reflect the value typed in the input field. For illustration purposes, this example then passes back an item that contains this pattern inside the item’s text. In a more real-life example, the `pattern` could be used to filter which of the items are passed to the callback.
## Using `onSetup`
`onSetup` is a complex property. It takes a function that is passed the component’s API and should return a callback that is passed the component’s API and returns nothing. This occurs because `onSetup` runs whenever the component is rendered, and the returned callback is executed when the component is destroyed. This is essentially an `onTeardown` handler, and can be used to unbind events and callbacks.
To clarify, in code `onSetup` may look like this:
```js
onSetup: (api) => {
// Do something here on component render, like set component properties or bind an event listener
return (api) => {
// Do something here on teardown, like unbind an event listener
};
};
```
To bind a callback function to an editor event use `editor.on(eventName, callback)`. To unbind an event listener use `editor.off(eventName, callback)`. Any event listeners *should* be unbound in the teardown callback. The only editor event which does not need to be unbound is `init` e.g. `editor.on('init', callback)`.
> **Note:**
> - The callback function for `editor.off()` should be the same function passed to `editor.on()`. For example, if a `editorEventCallback` function is bound to the `NodeChange` event when the button is created, `onSetup` should return `(api) => editor.off('NodeChange', editorEventCallback)`.
> - If `onSetup` does not have any event listeners or only listens to the `init` event, `onSetup` can return an empty function e.g. `return () => {};`.