---
title: "Creating custom dialogs"
description: "An overview of TinyMCE dialogs and how to create custom dialogs."
canonical_url: "https://www.tiny.cloud/docs/tinymce/latest/dialog/"
md_url: "https://www.tiny.cloud/docs/tinymce/6/dialog/index.md"
version: "6"
last_updated: "2022-04-07T05:31:36Z"
tokens: 752
---
Important This page documents TinyMCE 6. For new projects, Tiny recommends using the latest, most up-to-date version. [See TinyMCE 8 documentation](../../latest/dialog/).
# Creating custom dialogs

A dialog is a popup UI element that contains a header, body and footer, each containing specific types of sub-components. Dialogs also have an instance API and several configuration options, including configurable callback functions for certain dialog events.

> **Note:** TinyMCE also supports [URL dialogs](../urldialog/). Configuring a URL dialog is different to configuring a standard TinyMCE dialog.

## Use cases

### Display basic information

The [`code`](../code/) plugin’s dialog is an example of a simple dialog. It contains only one body panel component that displays the HTML code from the content.

![Source Code](../_images/sourcecode.png)

### Display complex information

More complex dialogs can use [tab panels](../dialog-components/#tabpanel) and various [layouts](../dialog-components/#layout-components) to categorise and organise information displayed to the user. For example, the [`help`](../help/) and [`character map`](../charmap/) plugins use dialogs with tabbed panels to categorise and separate information.

![Special Characters](../_images/specialchars.png)

### Interactive dialogs

TinyMCE dialogs can also contain [interactive components](../dialog-components/#basic-components) such as buttons, checkboxes and input fields.

For example, the [`image`](../image/) plugin’s dialog allows for users to link to or upload an image, input a description, title, class, caption, height and width, then insert it into the editor.

![Insert/Edit images](../_images/interactive.png)

## Body components

The body of a dialog must be either a [`panel`](../dialog-components/#panel) (a single panel) or a [`tabpanel`](../dialog-components/#tabpanel) (a collection of panels). Each panel can contain [panel components](../dialog-components/#panel-components) such as inputs, buttons and text.

> **Note:** TinyMCE also supports [URL dialogs](../urldialog/). Configuring a URL dialog is quite different to configuring a standard TinyMCE dialog.

### Panel

The basic dialog type is a **panel** dialog. A panel is a container for [panel components](../dialog-components/#panel-components). A panel type dialog only has one panel.

```js
{
  type: 'panel',
  items: [ ... ] // array of panel components
}
```

### TabPanel

A **tabpanel** dialog contains multiple panels, and a tab navigation menu on the left-hand side of the dialog to allow for switching between panels. Each panel can contain different [panel components](../dialog-components/#panel-components), allowing for complex dialogs.

See the [tab panel component reference](../dialog-components/#tabpanel) for tab panel configuration options.

```js
{
  type: 'tabpanel',
  tabs: [ // array of tab panel specifications
    {
      name: 'mytab',
      title: 'My Tab',
      items: [ ... ] // array of panel components
    },
    ...
  ]
}
```
The `name` of the panel can be used with the [`dialogApi.showTab('tabName')`](../dialog-apis/#dialog-api-methods) method to programmatically switch tabs. It is also passed to [`onTabChange`](../dialog-configuration/#configuration-options) as part of the `details` object.

#### Example tab panel

The Help plugin’s dialog is an example of a tab panel dialog.

![Help Button](../_images/help.png)