Creating custom Group toolbar buttons

A group toolbar button is a toolbar button that contains a collection of other toolbar buttons that are displayed in a pop-up when clicked. The style of toolbar shown is based on the current toolbar mode. For example, if toolbar_mode is set to floating, the toolbar group pop-up will appear in a floating shelf.

The group toolbar button is only supported when using the floating toolbar mode. If the toolbar_groups option is used with other toolbar modes, the toolbar group button will not be displayed and a warning message will be printed in the console.

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, in a custom icon pack, or added using the addIcon API.

tooltip

string

optional

Text for button tooltip.

items

string or LabelledToolbar[]

required

A string of space separated toolbar button names, or an array of labelled toolbar buttons.

onSetup

(api) => (api) => void

optional

default: () => () => {} - Function that’s invoked when the button is rendered. For details, see: Using onSetup.

context

string

optional

default: mode:design - The context property dynamically enables or disables the button based on the editor’s current state. For details, see: Context.

API

Name Value Description

isEnabled

() => boolean

Checks if the button is enabled.

setEnabled

(state: boolean) => void

Sets the button’s enabled state.

setText

(text: string) => void

Sets the text label to display.

setIcon

(icon: string) => void

Sets the icon of the button.

Group toolbar button example and explanation

The following is a simple group toolbar button example:

  • TinyMCE

  • HTML

  • JS

  • Edit on CodePen

<textarea id="custom-toolbar-group-button">
  <p><img style="display: block; margin-left: auto; margin-right: auto;" title="Tiny Logo" src="https://www.tiny.cloud/docs/tinymce/latest/_images/logos/android-chrome-256x256.png" alt="TinyMCE Logo" width="128" height="128"></p>
  <h2 style="text-align: center;">Welcome to the TinyMCE editor demo!</h2>
  <p>Select a menu item from the listbox above and it will insert contents into the editor at the caret position.</p>

  <h2>Got questions or need help?</h2>
  <ul>
    <li>Our <a href="https://www.tiny.cloud/docs/tinymce/8/">documentation</a> is a great resource for learning how to configure TinyMCE.</li>
    <li>Have a specific question? Try the <a href="https://stackoverflow.com/questions/tagged/tinymce" target="_blank" rel="noopener"><code>tinymce</code> tag at Stack Overflow</a>.</li>
    <li>We also offer enterprise grade support as part of <a href="https://www.tiny.cloud/pricing">TinyMCE premium plans</a>.</li>
  </ul>

  <h2>Found a bug?</h2>
  <p>If you think you have found a bug please create an issue on the <a href="https://github.com/tinymce/tinymce/issues">GitHub repo</a> to report it to the developers.</p>

  <h2>Finally ...</h2>
  <p>Need file uploads in your app? Consider using <a href="https://www.tiny.cloud/docs/tinymce/latest/uploadcare/" target="_blank" rel="noopener noreferrer">Uploadcare</a> with TinyMCE for a fast, modern upload experience.</p>
  <p>Thanks for supporting TinyMCE! We hope it helps you and your users create great content.
    <br>All the best from the TinyMCE team.</p>
</textarea>
tinymce.init({
  selector: 'textarea#custom-toolbar-group-button',
  height: 500,
  toolbar_mode: 'floating',
  toolbar: 'alignment',
  setup: (editor) => {

    /* example, adding a group toolbar button */
    editor.ui.registry.addGroupToolbarButton('alignment', {
      icon: 'align-left',
      tooltip: 'Alignment',
      items: 'alignleft aligncenter alignright | alignjustify'
    });

  },
  content_style: 'body { font-family:Helvetica,Arial,sans-serif; font-size:16px }'
});

The example above configures a custom alignment group toolbar button. When clicked the button will show a floating shelf containing the align left, center, right and justify toolbar buttons.

Using onSetup

onSetup accepts a function that receives the component’s API. This function should return a callback that returns nothing after being passed the component’s API. This occurs because onSetup runs whenever the component is rendered, and the callback returned by onSetup is executed when the component is destroyed. The function returned from onSetup is essentially an onTeardown handler, and can be used to unbind events and callbacks.

To clarify, in code onSetup may look like this:

onSetup: (api) => {
  // Runs when the component is created
  // Configure the component or bind event listeners

  return (api) => {
    // Runs when the component is destroyed
    // Unbind event listeners or clean up resources
  };
};

To bind a callback function to an editor event use +editor.off(eventName, callback)`]. To unbind an event listener use `xref:apis/tinymce.editor.adoc#off[`+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).

  • The callback function passed to editor.off() should be the same function passed to editor.on(). For example, if an 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 register any event listeners or only listens to the init event, onSetup can return an empty function e.g. return () => {};.