Configuring custom dialogs

A dialog configuration has three main parts to match the three main parts of the dialog’s UI:

  • Title: The title of the dialog. This will display in the header of the dialog.

  • Body: The body of the dialog. The body component can be a panel or a tab panel, which can contain an array of panel components such as buttons, inputs and text.

  • Buttons: An array of footer buttons that are displayed in the dialog’s footer.

Basic example

The configuration for a basic dialog that displays HTML information might look like this:{
  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: [ // A list of footer buttons
      type: 'submit',
      text: 'OK'


Name Value Requirement Description




The title of the dialog. This will display in the header of the dialog.


panel or tabpanel component


The specification for the body component.




An array of footer buttons to render in the footer of the dialog.


'normal', 'medium' or 'large'


default: normal - Dialog size options.




An object containing initial values for the dialog’s panel components.


(dialogApi, details) => void


Function invoked when a user interacts with a button type panel component, clicks a Custom type footer button, or clicks an item in a Menu type footer button.


(dialogApi) => void


Function invoked when a Submit type footer button is clicked.


(dialogApi) => void


Function invoked when the dialog is cancelled. The dialog header’s close button and a Cancel type footer button invoke this function.


(dialogApi, details) => void


Function invoked when the value of an input type panel component changes.


() => void


Function invoked when the dialog is closed. The dialog header’s close button, a Cancel type footer button and the dialog instance API’s close() method invoke this function.


(dialogApi, details) => void


This method only applies to tab panel dialogs. Function invoked when the user changes tabs. details is an object that contains newTabName and oldTabName.

For more information on the dialogApi object that is passed to some of the configuration options, see the dialog instance API documentation.

Event callback functions

Each of the event callback functions - onAction, onSubmit, onCancel, onChange, onClose, and onTabChange - are shared between all dialog components that may trigger them. For example, Custom type footer buttons and dialog panel buttons all trigger onAction. Therefore, callback functions that may be triggered by multiple components are passed an object (called details above) that contains the name of the component that triggered the event.

Any callback function that is not passed a details object assumes that the dialog will only contain one component which can trigger it or that it does not matter if the function is triggered by multiple components. For example, onSubmit is only triggered when a user clicks on a Submit type footer button, and TinyMCE assumes that a dialog will only have one Submit type button. In comparison, onCancel and onClose are both triggered by clicking the X button in the top right of a dialog or by clicking a Cancel type footer button. These two buttons have the same functionality, and therefore TinyMCE does not differentiate between them.