Toolbar buttons

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 toolbar buttons

The methods for adding custom toolbar buttons are in the UI Registry part of the editor API editor.ui.registry. The API has four methods for adding toolbar buttons, one for each type of toolbar button:

  • editor.ui.registry.addButton(identifier, configuration)

  • editor.ui.registry.addToggleButton(identifier, configuration)

  • editor.ui.registry.addSplitButton(identifier, configuration)

  • editor.ui.registry.addMenuButton(identifier, configuration)

  • editor.ui.registry.addGroupToolbarButton(identifier, configuration)

The two arguments these methods take are:

  • identifier - a unique name for the button

  • configuration - an object containing your configuration for that button.

Some configuration options are common to all types of toolbar buttons, but some toolbar button types also have custom configuration options. Review the relevant documentation for each type of button for more information.

To create a custom toolbar button, define and register the button within the setup callback of the TinyMCE configuration. This callback is invoked automatically for every initialized editor instance. UI components must be defined within the setup callback because the callback receives a reference to the editor instance as its argument, which is used to access the UI registry API. Once registered, the button can be added to the editor by adding the identifier string it was registered with to the toolbar configuration option.

Example of adding a basic button that triggers an alert when clicked

tinymce.init({
  selector: '#editor',
  toolbar: 'myCustomToolbarButton',
  setup: function (editor) {
    editor.ui.registry.addButton('myCustomToolbarButton', {
      text: 'My Custom Button',
      onAction: function () {
        alert('Button clicked!');
      }
    });
  }
});

Toolbar Buttons Example

The following example creates different types of toolbar buttons.

  • TinyMCE

  • HTML

  • JS

  • Edit on CodePen

<textarea id="toolbar-button">
  <p>Hello world</p>
</textarea>
tinymce.init({
  selector: 'textarea#toolbar-button',
  toolbar: 'basicDateButton selectiveDateButton toggleDateButton splitDateButton menuDateButton',
  setup: function (editor) {

    /* Helper functions */
    var toDateHtml = function (date) {
      return '<time datetime="' + date.toString() + '">' + date.toDateString() + '</time>';
    };
    var toGmtHtml = function (date) {
      return '<time datetime="' + date.toString() + '">' + date.toGMTString() + '</time>';
    };
    var toIsoHtml = function (date) {
      return '<time datetime="' + date.toString() + '">' + date.toISOString() + '</time>';
    };

    /* Basic button that just inserts the date */
    editor.ui.registry.addButton('basicDateButton', {
      text: 'Insert Date',
      tooltip: 'Insert Current Date',
      onAction: function (_) {
        editor.insertContent(toDateHtml(new Date()));
      }
    });

    /* Basic button that inserts the date, but only if the cursor isn't currently in a "time" element */
    editor.ui.registry.addButton('selectiveDateButton', {
      icon: 'insert-time',
      tooltip: 'Insert Current Date',
      disabled: true,
      onAction: function (_) {
        editor.insertContent(toDateHtml(new Date()));
      },
      onSetup: function (buttonApi) {
        var editorEventCallback = function (eventApi) {
          buttonApi.setDisabled(eventApi.element.nodeName.toLowerCase() === 'time');
        };
        editor.on('NodeChange', editorEventCallback);
        return function (buttonApi) {
          editor.off('NodeChange', editorEventCallback);
        }
      }
    });

    /* Toggle button that inserts the date, but becomes inactive when the cursor is in a "time" element */
    /* so you can't insert a "time" element inside another one. Also gives visual feedback. */
    editor.ui.registry.addToggleButton('toggleDateButton', {
      icon: 'insert-time',
      tooltip: 'Insert Current Date',
      onAction: function (_) {
        editor.insertContent(toDateHtml(new Date()));
      },
      onSetup: function (buttonApi) {
        var editorEventCallback = function (eventApi) {
          buttonApi.setActive(eventApi.element.nodeName.toLowerCase() === 'time');
        };
        editor.on('NodeChange', editorEventCallback);
        return function (buttonApi) {
          editor.off('NodeChange', editorEventCallback);
        }
      }
    });

    /* Split button that lists 3 formats, and inserts the date in the selected format when clicked */
    editor.ui.registry.addSplitButton('splitDateButton', {
      text: 'Insert Date',
      onAction: function (_) {
        editor.insertContent('<p>Its Friday!</p>')
      },
      onItemAction: function (buttonApi, value) {
        editor.insertContent(value);
      },
      fetch: function (callback) {
        var items = [
          {
            type: 'choiceitem',
            text: 'Insert Date',
            value: toDateHtml(new Date())
          },
          {
            type: 'choiceitem',
            text: 'Insert GMT Date',
            value: toGmtHtml(new Date())
          },
          {
            type: 'choiceitem',
            text: 'Insert ISO Date',
            value: toIsoHtml(new Date())
          }
        ];
        callback(items);
      }
    });

    /* Menu button that has a simple "insert date" menu item, and a submenu containing other formats. */
    /* Clicking the first menu item or one of the submenu items inserts the date in the selected format. */
    editor.ui.registry.addMenuButton('menuDateButton', {
      text: 'Date',
      fetch: function (callback) {
        var items = [
          {
            type: 'menuitem',
            text: 'Insert Date',
            onAction: function (_) {
              editor.insertContent(toDateHtml(new Date()));
            }
          },
          {
            type: 'nestedmenuitem',
            text: 'Other formats',
            getSubmenuItems: function () {
              return [
                {
                  type: 'menuitem',
                  text: 'GMT',
                  onAction: function (_) {
                    editor.insertContent(toGmtHtml(new Date()));
                  }
                },
                {
                  type: 'menuitem',
                  text: 'ISO',
                  onAction: function (_) {
                    editor.insertContent(toIsoHtml(new Date()));
                  }
                }
              ];
            }
          }
        ];
        callback(items);
      }
    });
  },
  content_style: 'body { font-family:Helvetica,Arial,sans-serif; font-size:14px }'
});