contexttoolbar.adoc

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. 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.

partial$context/positioning.adoc

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.

liveDemo::context-toolbar[height="600", tab="js"]

Add labels and groups for context toolbar buttons

From {productname} 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

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:

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)
    });
  }
});

liveDemo::context-toolbar-labels[height="600", tab="js"]

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.

partial$context/priority.adoc