---
title: "Creating custom Group toolbar buttons"
description: "Creating custom Group toolbar buttons for TinyMCE"
canonical_url: "https://www.tiny.cloud/docs/tinymce/latest/custom-group-toolbar-button/"
md_url: "https://www.tiny.cloud/docs/tinymce/6/custom-group-toolbar-button/index.md"
version: "6"
last_updated: "2023-04-14T00:45:15Z"
tokens: 1093
---
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-group-toolbar-button/).
# 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](../toolbar-configuration-options/#toolbar_mode). For example, if `toolbar_mode` is set to `floating`, the toolbar group pop-up will appear in a floating shelf.

> **Note:** 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](../editor-icon-identifiers/), in a [custom icon pack](../creating-an-icon-pack/), or added using the [`addIcon` API](../apis/tinymce.editor.ui.registry/#addIcon). |
| 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](../toolbar-configuration-options/#adding-toolbar-group-labels). |
| 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. |

## Group toolbar button example and explanation

The following is a simple group toolbar button example:

**Example**

```js
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` 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 () => {};`.