---
title: "Context toolbar"
description: "Creating custom context toolbars for TinyMCE 7"
canonical_url: "https://www.tiny.cloud/docs/tinymce/latest/contexttoolbar/"
md_url: "https://www.tiny.cloud/docs/tinymce/7/contexttoolbar/index.md"
version: "7"
last_updated: "2025-04-09T03:20:42Z"
tokens: 2394
---
Important This page documents TinyMCE 7. For new projects, Tiny recommends using the latest, most up-to-date version. [See TinyMCE 8 documentation](../../latest/contexttoolbar/).
# Context toolbar

A context toolbar can only contain either buttons that are defined for a normal toolbar, or buttons specifically registered for launching a [ContextForm](../contextform/). The buttons comes as a list of strings, where each string is a registered name of a button.

## Registering a context toolbar

A context toolbar is registered by calling the `addContextToolbar` API in the registry. The specification is as follows:

| Name | Description |
| --- | --- |
| `predicate` | This controls when the context toolbar will appear |
| `position` | This controls where the context toolbar will appear with regards to the current cursor |
| `scope` | This controls whether the predicate (condition) is a `node` -based predicate, or an `editor` -based predicate. See context toolbar priority section below, for more details. |
| `items` | A list of strings which represent either a registered toolbar button, or a registered context form launcher. |

## Positioning of context toolbars

There are three options for positioning context toolbars: `selection`, `node`, or `line`.

- A `selection` position will place the context toolbar above or below the current selection, centered if possible.
- A `node` position will place the context toolbar above or below the bounds of a node (e.g. a table or image).
- A `line` position will place the context toolbar to the right (or left in Right-to-Left languages) of the current selection.

## Example configuration

This example shows how the quickbars plugin adds the standard selection context toolbar and an example of a custom toolbar for image alignment. The context toolbar will show whenever any content is selected.

**Example**

```js
tinymce.init({
  selector: 'textarea#context-toolbar',
  height: 350,
  setup: (editor) => {
    editor.ui.registry.addContextToolbar('imagealignment', {
      predicate: (node) => node.nodeName.toLowerCase() === 'img',
      items: 'alignleft aligncenter alignright',
      position: 'node',
      scope: 'node'
    });

    editor.ui.registry.addContextToolbar('textselection', {
      predicate: (node) => !editor.selection.isCollapsed(),
      items: 'bold italic | blockquote',
      position: 'selection',
      scope: 'node'
    });
  },
  content_style: 'body { font-family:Helvetica,Arial,sans-serif; font-size:16px }'
});
```

## Add labels and groups for context toolbar buttons

From TinyMCE 7.6.0 onward, registering a context toolbar allows specifying `items` as an object that supports grouping with optional names and labels. This improvement enhances toolbar usability by organizing buttons into titled or labeled groups.

The object structure takes two optional properties: `name` and `label`.

- `name`: property is used as the group’s title for the group that contains the buttons.
- `label`: property is used as a label for each group of buttons.

> **Note:** If neither `name` nor `label` are specified, the behavior defaults to ungrouped buttons.
The object structure for `items` is as follows:

Example of a context toolbar configuration with groups and labels
```js
items: [
  {
    name: 'Formatting', // Optional, used as the group's title
    items: [ 'bold', 'italic' ] // Array of registered button names
  },
  {
    label: 'History', // Optional, used as a label for the group
    items: [ 'undo', 'redo' ] // Array of registered button names
  },
  {
    items: [ 'undo', 'italic' ] // No name or label specified, default behavior applies
  }
]
```

> **Note:** For editors using 7.8.0+, context toolbars also support the `navigateback` button for multi-level toolbar navigation. This built-in button allows returning to the previous context toolbar when using nested toolbars.
Example of a multi-level context toolbar configuration:
```js
tinymce.init({
  selector: 'textarea',
  setup: (editor) => {
    // Register the main context toolbar named 'bar'
    editor.ui.registry.addContextToolbar('bar', {
      predicate: () => true, // Always show the toolbar when triggered
      items: 'bold italic | undo redo | subbar1', // Toolbar buttons and nested toolbar trigger
      position: 'line',
      scope: 'editor'
    });

    // Register a nested context toolbar named 'subbar1'
    editor.ui.registry.addContextToolbar('subbar1', {
      launch: { text: 'Subbar 1' }, // Button label that appears in the parent toolbar
      items: 'navigateback bold italic | undo redo | subbar2'
      // 'navigateback' allows users to return to the previous toolbar
      // 'subbar2' is another nested toolbar (can be defined similarly)
    });
  }
});
```
**Example**

```js
tinymce.init({
  selector: 'textarea#context-toolbar-labels',
  height: 350,
  setup: (editor) => {
    editor.ui.registry.addContextToolbar('imagealignment', {
      predicate: (node) => node.nodeName.toLowerCase() === 'img',
      position: 'node',
      scope: 'node',
      items: [
        {
          name: 'Formatting',
          items: ['alignleft', 'aligncenter', 'alignright']
        },
        {
          label: 'Copy',
          items: ['copy', 'paste']
        }
      ],
    });

    editor.ui.registry.addContextToolbar('textselection', {
      predicate: (node) => !editor.selection.isCollapsed(),
      position: 'selection',
      scope: 'node',
      items: [
        {
          name: 'Format',
          items: ['bold', 'italic', 'underline']
        },
      ],
    });
  },
  content_style: 'body { font-family:Helvetica,Arial,sans-serif; font-size:16px }'
});
```

## Launching a context toolbar programmatically

There is an `editor` event called `contexttoolbar-show` that can be fired to show a context toolbar at the current selection. The event takes a parameter `toolbarKey` which specifies the name of the registered context form or context toolbar to show.

## Troubleshooting context toolbar and context form conflicts

There are situations where custom context toolbars or custom context forms may conflict with:

- Context toolbars or context forms provided by the editor,
- Context toolbars or context forms provided by the [Quick Toolbars (`quickbars`) plugin](../quickbars/),
- Other custom context toolbars or custom context forms.

### Determining the display priority of context toolbars and context forms

There are three settings that determine the priority of context toolbars and context forms: `scope`, `predicate`, and `position`.

- `scope` - Sets the context toolbar or form as either: specific to certain types of content (`node`), or a general (global) toolbar or form (`editor`).
- `predicate` - The predicate is the condition(s) where the context toolbar or form should be shown. This setting is a function for determining if the context menu or form applies to the current selection or cursor position. This function should return a boolean value.
- `position` - Sets where the context toolbar or form is rendered, relative to the current context (`selection`, `node`, or `line`).
Generally:

- Context *forms* are prioritized over context *toolbars*.
- Context *forms* with `scope: 'node'` are prioritized over `scope: 'editor'`.
- Only one context *form* can be shown for a selection or cursor position, they cannot be concatenated to another context *form* or a context *toolbar*.
- Context *toolbars* with `position: 'selection'` are prioritized over `position: 'node'`, and `position: 'line'` is given the lowest priority.
- The editor concatenates context *toolbars* when there is more than one context *toolbar* to display with:

  - A matching predicate,
  - The same `scope` and `position` values.

Concatenated toolbars may contain duplicate toolbar items.
- If no matching context toolbars or context forms are found for the selection or cursor position, then editor will recursively search for matches on the parent node of the current node, until it reaches the root node of the editor content.

#### Description of how context toolbars and context forms are prioritized

The following description can be used for troubleshooting the behavior of context toolbars and context forms.

The editor will determine which context toolbars or context form will be shown using following process:

1. Find all **context forms** with both:

  - `scope: 'node'`
  - A predicate (condition) matching the current selection or cursor position.

If there are any matching **context forms**, the first one found will be displayed in the editor and the process will end.
2. Find all **context forms** with both:

  - `scope: 'editor'`
  - A predicate matching the current selection or cursor position.

If there are any matching **context forms**, the first one found will be displayed in the editor and the process will end.
3. Find all **context toolbars** with both:

  - Any `scope`
  - A predicate matching the current selection or cursor position.

If there are any matching **context toolbars**, the editor will prioritize the context toolbars based on the `position` value.
  - All context toolbars with `position: 'selection'` or `position: 'node'` will be concatenated, the concatenated toolbar will be displayed, and the process will end.
  - Otherwise, all context toolbars with `position: line` will be concatenated, the concatenated toolbar will be displayed, and the process will end.
4. Find all **context forms** with both:

  - Any `scope`
  - A predicate matching the **parent node** of the current node, selection, or cursor position.

If there are any **context forms** found, the first one found will be displayed in the editor and the process will end.
5. Find all **context toolbars** with both:

  - Any `scope`
  - A predicate matching the **parent node** of the current node, selection, or cursor position.

If there are any matching **context toolbars**, the editor will prioritize the context toolbars based on the `position` value.
  - If there are context toolbars with `position: 'selection'`, they will be concatenated, the concatenated toolbar will be displayed, and the process will end.
  - If there are context toolbars with `position: 'node'`, they will be concatenated, the concatenated toolbar will be displayed, and the process will end.
  - Otherwise, all context toolbars with `position: line` will be concatenated, the concatenated toolbar will be displayed, and the process will end.
6. Repeat step 4 and 5 for each successive parent node in the DOM for context toolbars and context forms with `scope: node` until either:

  - A matching context form or context toolbars are found and displayed,
  - The root node of the editor is reached.