Custom dialog footer buttons

A button is a clickable component that can contain text or an icon. There are three types of buttons (primary, secondary and menu buttons). Primary and secondary buttons will perform an action when clicked, however they are styled differently. Primary buttons are intended to stand out. The color will depend on the chosen skin. Menu buttons will open a menu with more options when clicked, instead of performing an action.

Dialog footer buttons are different to dialog panel buttons.

Configuration

Name Type Requirement Description

type

'submit' or 'cancel' or 'custom' or 'menu'

required

Must be 'submit', 'cancel', 'custom' or 'menu' based on the type of callback function that should be invoked when the button is clicked.

text

string

required

Text to display in the button if icon is not specified. Also used for the button’s title attribute.

name

string

optional

An identifier for the button. If not specified, the button will be assigned a randomly generated name.

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. When configured, the button will display the icon instead of text.

buttonType

'primary', or 'secondary'

optional

default: 'secondary' - Whether to style the button as a primary, or secondary button.

enabled

boolean

optional

default: true - When false, the button will be disabled when the dialog loads.

align

'end' or 'start'

optional

default: 'end' - When set to 'end' the button will display on the right-hand side of the dialog. When set to 'start' the button will display on the left-hand side.

NOTE: This feature is only available for TinyMCE 7.4 and later.

context

string

optional

default: mode:design for all types except cancel, which defaults to any - The context property dynamically enables or disables the menu item based on the editor’s current state. For details, see: Context.
Buttons do not support mixing icons and text at the moment.

Disabling and enabling buttons

To toggle between a button’s disabled and enabled states, use setEnabled(name, state) function from the dialog instance API, where name is the identifier the button was configured with and state is whether the button should be enabled or disabled.

Button types and event callbacks

The different footer button types will invoke different callbacks when clicked:

  • A Submit type button will invoke the onSubmit callback function provided in the dialog configuration.

  • A Cancel type button will invoke the onCancel and onClose callback functions. These callback functions are also fired when a user clicks the X button in the top right of the dialog.

  • A Custom type button will invoke the onAction callback function, and pass it the button’s name in the details object. This allows developers to create a click handler for each Custom type footer button in the dialog. See the Redial example for an example of how to use this.

  • A Menu type button will fetch a list of options and display them in a drop-down menu. When a menu button item is clicked, the item name is passed to the dialog onAction callback. For details, see: Dialog menu buttons.

See the dialog configuration options documentation for more information.

{
  type: 'submit', // button type
  name: 'submitButton', // identifying name
  text: 'Submit', // text for the button
  // icon: 'checkmark', // will replace the text if configured
  enabled: true, // button is active when the dialog opens
  buttonType: 'primary', // style the button as a primary button
  align: 'start', // align the button to the left of the dialog footer
  context: 'mode:design' // button is active when the editor is in design mode, only effective if enabled is true
}

Dialog menu buttons

A dialog menu button is a drop-down button that can be used to provide a drop-down list of items in a dialog footer.

When dialog menu items are clicked, a dialog onAction callback is triggered. The name of the menu item is passed into the onAction callback. Clicking on the menu footer button won’t trigger any callbacks and will only open the menu of specified items.

Dialog menu button

The following options can be specified for a dialog menu button:

Name Value Requirement Description

items

array

required

An array of dialog menu items.

name

string

optional

An identifier for the button. If not specified, the button will be assigned a randomly generated name.

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.

Dialog menu items

The following options can be specified for a dialog menu button item:

Name Value Requirement Description

name

string

required

Identifier for the dialog menu item which is passed to the dialog onAction callback. name can be used with initialData to set the initial state.

type

string

required

The type togglemenuitem should be used.

text

string

optional

Text to display if no icon is found.

value

string

optional

A value to associate with the menu item.

NOTE: This feature is only available for TinyMCE 7.4 and later.

context

string

optional

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

 
buttons: [
  {
    type: 'menu', // button type
    name: 'myMenuButton', // identifying name
    text: 'My Menu', // text for the button
    // icon: 'user', // will replace the text if configured
    enabled: true, // button is active when the dialog opens
    align: 'start', // align the button to the left of the dialog footer
    tooltip: 'This is "My" button.',
    items: [
      {
        name: 'dialogMenuButtonItem1',
        type: 'togglemenuitem',
        text: 'Item 1.',
        context: 'mode:design'
      },
      {
        name: 'dialogMenuButtonItem2',
        type: 'togglemenuitem',
        text: 'Item 2.',
        context: 'mode:design'
      }
    ]
  }
]
This feature is only available for TinyMCE 6.6 and later.

In addition to its usual functions, the buttons property can also be used to stop the footer section from displaying.

To configure a custom dialog so it does not render a footer section when displayed, set the buttons property to an empty array, [], or omit it entirely.

tinymce.activeEditor.windowManager.open({
  title: 'Dialog Title', // The dialog's title - displayed in the dialog header
  body: {
    type: 'panel', // The root body type - a Panel or TabPanel
    items: [ // A list of panel components
      {
        type: 'htmlpanel', // an HTML panel component
        html: 'Panel content goes here.'
      }
    ]
  },
  buttons: []
});