Context menus

The context menu is a configurable component that appears when the user right clicks in the editable area. By default it does not disable the operating system’s native context menu, if there are no items to display at the cursor position the native context menu will be shown.

The context menu supports both individual menu items and dynamic context menu sections.

Interactive example

  • TinyMCE

  • HTML

  • JS

  • Edit on CodePen

<textarea id="context-menu">
  <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>
    Please try out the features provided in this basic example.<br>
    Note that any <strong>MoxieManager</strong> file and image management functionality in this example is part of our commercial offering – the demo is to show the integration.
  </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>A simple table to play with</h2>

  <table style="border-collapse: collapse; width: 100%;" border="1">
    <thead>
      <tr>
        <th>Product</th>
        <th>Cost</th>
        <th>Really?</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td style="text-align: center;">TinyMCE</td>
        <td style="text-align: center;">Free</td>
        <td style="text-align: center;">YES!</td>
      </tr>
    </tbody>
  </table>

  <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#context-menu',
  height: 500,
  plugins: 'link image table lists',
  contextmenu: 'link image table',
  content_style: 'body { font-family:Helvetica,Arial,sans-serif; font-size:16px }'
});

Options

contextmenu

The contextmenu option allows you to specify which items appear on the context menu. The format of this option is a space separated list of items in a string, or an array of item names.

The context menu option accepts three styles of item:

  • Any registered menu item.

  • A "|" pipe character to indicate a separator should be added to delineate a group of menu items.

  • Context menu sections defined by a plugin (usually equal to the plugin name). Separators are automatically inserted between context menu sections.

If the same name is registered as both a context menu section and a menu item, the context menu section takes preference.

The default configuration includes the context menu sections for the following plugins: link, linkchecker , image, editimage, permanentpen, table, and tinymcespellchecker.

To disable the editor’s context menu, set this option to false.

Type: String, Array of strings, or false

Default value: 'link linkchecker image editimage table spellchecker configurepermanentpen'

When the TinyMCE context menu is enabled, users can still access the browser context menu, including the browser spellchecker, using the Ctrl+Right click shortcut. However if the contextmenu_never_use_native option is enabled, holding the Ctrl key will have no effect.
When a TinyMCE context menu is configured, a user on a mobile device can access the TinyMCE context menu by a long press. However, when a TinyMCE context menu is not configured but a TinyMCE context toolbar is, long press will open the context toolbar instead.

Example: using contextmenu

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  plugins: 'link image table',
  contextmenu: 'link image table'
});

contextmenu_never_use_native

The contextmenu_never_use_native option allows you to prevent the browser context menu from appearing within the editor.

Using this option may result in unexpected behavior when right-clicking in text areas. We advise you to consider all your options carefully before using this feature.

Type: Boolean

Default value: false

Possible values: true, false

Example: using contextmenu_never_use_native

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  contextmenu_never_use_native: true
});

Available context menu sections

The following table shows all context menu sections, including sections provided by plugins. Any menu item can also be added to the context menu. To retrieve a list from the editor, run the following command from the browser console:

tinymce.activeEditor.ui.registry.getAll().contextMenus

The identifier below will add a context menu section containing one or more items. It is not possible to add individual items from the following context menu sections.

A section adds items only when the context menu is opened on matching content, as described in the Appears when column. On other content, the section is left out of the menu. A section also appears only if its identifier is in the contextmenu option. The default value does not include advtemplate, lists, or math.

Identifier Core/Plugin Appears when Description

advtemplate

Templates

The advtemplate_create_template option is set. The item shows anywhere in the editor, but is enabled only when content is selected.

Adds the Save as template…​ item for saving the selected content as a template.

configurepermanentpen

Permanent Pen

The permanent pen is in use.

Adds the Permanent pen properties…​ item for opening the Permanent Pen Properties dialog.

editimage

Image Editing

The context menu is opened on an image that the plugin can edit: an image on the same host as the page, a data: or blob: image, an image from a host in editimage_cors_hosts, or any image when an image proxy is configured.

Adds the Edit image item for opening the Edit Image dialog.

image

Image

The context menu is opened on an existing, editable image.

Adds the Image…​ item for opening the Insert/Edit Image dialog to edit the selected image. This section does not add an item for inserting a new image. To insert an image, use the image toolbar button or the image menu item in the Insert menu.

link

Link

The context menu is opened on editable content.

Adds the Link…​ item for opening the Insert/Edit Link dialog. When the context menu is opened on a link, the Remove link and Open link items are also added.

linkchecker

Link Checker

The context menu is opened on a link marked as broken.

Adds the Ignore item, allowing the user to instruct linkchecker to ignore the link. When the contextmenu option does not include link, the section also adds the Remove link and Open link items, and the Link…​ item when the Link plugin is loaded.

lists

Lists

The context menu is opened in an ordered (numbered) list.

Adds the List properties…​ item for opening the List Properties dialog.

math

Math

The context menu is opened on a math equation.

Adds the Math…​ item for editing the equation.

spellchecker

Spell Checker

The context menu is opened on a misspelled word.

Adds a list of suggested corrections, an Ignore item, and an Ignore all item.

table

Table

The context menu is opened in a table.

Adds table related context menu items, including Enhanced Tables context menu items (if the Enhanced Tables plugin is enabled). In a table caption, only the table properties and delete table items are added.

For a list of available menu items that can be added to the context menu, see: Menu Items Available for TinyMCE.

Registering context menu sections

The structure of context menu sections is a simple query system indexed by name. We strongly recommend using the name of the plugin as the context menu name for ease of configuration.

In the menu shown to the user, sections are delineated by separators. Sections can return an empty array of menu items to indicate that section has no applicable items to the current context and should not be shown.

type ContextMenuApi = {
  update: (element: Element) => string | Array<ContextMenuContents>
}

editor.ui.registry.addContextMenu(name: string, feature: ContextMenuApi);

Every time the user opens the context menu, the selected element is passed to the update function which must return either a space separated string or an array of items to display. The types of the items returned are as follows:

type ContextMenuContents = string | ContextMenuItem | SeparatorMenuItemApi | ContextSubMenu

type ContextMenuItem = {
  type?: 'item';
  text: string;
  icon?: string;
  shortcut?: string;
  disabled?: boolean;
  onAction: () => void;
}
type ContextSubMenu = {
  type: 'submenu';
  text: string;
  icon?: string;
  shortcut?: string;
  disabled?: boolean;
  getSubmenuItems: () => string | Array<ContextMenuContents>;
}

type SeparatorMenuItemApi = {
  type: 'separator'
}

The most common type to use is string, which references an existing registered menu item.

ContextMenuItem, ContextSubMenu and SeparatorMenuItemApi types are intended for use by plugins with completely dynamic menu requirements, where registering each menu item is not necessary. For example, the spellchecker shows a list of suggestions specific to the selected word.

When creating a dynamic menu, the structure type properties are used in order to support untyped API usage:

  • type item (default) is a regular menu item, and must have an onAction method.

  • type submenu must have getSubmenuItems, and if it has an onAction property it is ignored.

  • type separator ignores all other properties.

Defining a context menu section

This example shows how the image plugin dynamically adds the standard image menu section to the context menu. The image context menu section is empty unless the selected element is an image.

  • TinyMCE

  • HTML

  • JS

  • Edit on CodePen

<textarea id="contextmenu-section">
  <p>Right click on the example image below will show the newly configured context menu.</p>

  <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>
  <p>Right Clicking on text should not invoke the context menu</p>
</textarea>
tinymce.PluginManager.add('my-example-plugin', (editor) => {
  editor.ui.registry.addMenuItem('image', {
    icon: 'image',
    text: 'Image',
    onAction: () => {
      console.log('context menu clicked');
      alert('context menu clicked');
    }
  });

  editor.ui.registry.addContextMenu('image', {
    update: (element) => !element.src ? '' : 'image'
  });
});

tinymce.init({
  selector: 'textarea#contextmenu-section',
  contextmenu: 'image',
  plugins: 'my-example-plugin',
  content_style: 'body { font-family:Helvetica,Arial,sans-serif; font-size:16px }'
});