--- title: "Context forms" description: "Creating custom context forms for TinyMCE 6" canonical_url: "https://www.tiny.cloud/docs/tinymce/latest/contextform/" md_url: "https://www.tiny.cloud/docs/tinymce/6/contextform/index.md" version: "6" last_updated: "2023-04-19T00:21:16Z" tokens: 3166 --- Important This page documents TinyMCE 6. For new projects, Tiny recommends using the latest, most up-to-date version. [See TinyMCE 8 documentation](../../latest/contextform/). # Context forms A context form consists of an input field, and a series of related buttons. Context forms can be shown wherever a context toolbar can be shown. Also, when a context form is registered containing a `launch` configuration, a special context toolbar button with name `form:${name}` is registered which will launch that particular context form. Context forms are a generalization of the `Insert Link` form that existed in the original [inlite](/docs-4x/themes/inlite/#quicklink) theme from TinyMCE 4. ## Registering a context form A context form is registered by calling the `addContextForm` API in the registry. The specification of a context form is separated into two parts: ### Launch The button strings for launching a context form is `form:${name}` where name is the registered name of the context form (e.g. form:link). > **Note:** These buttons will only be present if the `launch` setting of the context form is specified. The Launch specification. This relates to what the button that launches this form will look like. | Name | Details | | --- | --- | | `launch` | This is the specification for the launching button that can appear in a context toolbar only. It will be either type: `contextformbutton` or `contextformtogglebutton`, and will be identical to those definitions below except it will **not** have an `onAction`. | #### Launching context forms from a context toolbar If a registered context form has a `launch` setting, then it can be launched from a context toolbar. The name of item will be `form:${name}` (e.g. 'form:link'). When the user presses this button, the toolbar will change into the specified context form. If you the user presses `Esc` in a context form that was launched through a context toolbar, they will be returned to the original context toolbar. #### Launching a context form programmatically There is an `editor` command, `contexttoolbar-show`, that can be dispatched to show a context form at the current selection. The command takes a parameter, `toolbarKey`, which specifies the name of the registered context form or context toolbar to show. ### Form This relates to the form itself. The form specifications are: | Name | Details | | --- | --- | | `launch` | This is the specification for the launching button that can appear in a context toolbar only. It will be either type: `contextformbutton` or `contextformtogglebutton`, and will be identical to those definitions below except it will **not** have an `onAction`. | | `label` | This is the label that will appear in the form. | | `initValue` | This is the initial value the input will have in the form. | | `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 for more details. | | `commands` | This is a list of the items to show in the context form. They can be either `contextformbutton` or `contextformtogglebutton`. | ### Positioning of context forms There are three options for positioning context forms: `selection`, `node`, or `line`. - A `selection` position will place the context form above or below the current selection, centered if possible. - A `node` position will place the context form above or below the bounds of a node (e.g. a table or image). - A `line` position will place the context form to the right (or left in Right-to-Left languages) of the current selection. ## Context form buttons Unlike normal context toolbar buttons, Context form buttons are not registered beforehand. Instead, you need to define each button completely in the `commands` section. ### Context form button The definition of a context form button is very similar to the definition of a normal toolbar button. The main difference is that the action is slightly different (as it will relate to the form), and the type is `contextformbutton` instead of `button`. The following is the full list of options: #### type: 'contextformbutton'; | Name | Value | Requirement | Description | | --- | --- | --- | --- | | primary | boolean | Optional | This will activate the button on in the input form. | | onAction | `(formApi, togglebuttonApi) => void` | Required | This decides what happens when the user clicks the button. | | active | boolean | Optional | default: `false` | | enabled | boolean | Optional | default: `true` - Represents button state. Is toggled by the button’s API | | tooltip | string | Optional | Text for button tooltip. | | text | string | Optional | Text to display if no icon is found. | | icon | string | Optional | Name of the icon to be displayed. Must correspond to an icon: in the [icon pack](../editor-icon-identifiers/), in a [custom icon pack](../creating-an-icon-pack/), or added using the [`addIcon` API](../apis/tinymce.editor.ui.registry/#addIcon). | | onSetup | `(togglebuttonApi) => (togglebuttonApi) => void` | Optional | default: `() => () => {}` - Function that’s invoked when the button is rendered. | Where the `buttonApi` is the same as a regular toolbar button and `FormApi` has `(getValue: () => string, hide: () => void)` ### Context form toggle button The context form toggle button is very similar to the a normal toolbar toggle button. The main difference is that the action is slightly different (as it will relate to the form), and the type is `contextformtogglebutton`, instead of `togglebutton`. The following is the full list of options: #### type: 'contextformtogglebutton'; | Name | Value | Requirement | Description | | --- | --- | --- | --- | | primary | boolean | Optional | This will activate the button on in the input form. | | onAction | `(formApi, togglebuttonApi) => void` | Required | This decides what happens when the user clicks the button. | | active | boolean | Optional | default: `false` | | enabled | boolean | Optional | default: `true` - Represents button state. Is toggled by the button’s API | | tooltip | string | Optional | Text for button tooltip. | | text | string | Optional | Text to display if no icon is found. | | icon | string | Optional | Name of the icon to be displayed. Must correspond to an icon: in the [icon pack](../editor-icon-identifiers/), in a [custom icon pack](../creating-an-icon-pack/), or added using the [`addIcon` API](../apis/tinymce.editor.ui.registry/#addIcon). | | onSetup | `(togglebuttonApi) => (togglebuttonApi) => void` | Optional | default: `() => () => {}` - Function that’s invoked when the button is rendered. | Where the `toggleButtonApi` is the same as a regular toolbar toggle button. ### formApi Both `contextformbutton` and `contextformtogglebutton` are passed `formApi` in their `onAction` callback. The `formApi` has two functions: | Functions | Description | | --- | --- | | `hide` | This will hide the form. By default, no button hides the form. It is the responsibility of the developer to hide the form in the `onAction` handler of buttons that require that the context form close after the action. | | `getValue` | This will retrieve the value current typed in the input field. | ## Example configuration This example shows how the link plugin adds the standard link context form. The context form will show whenever any content is selected. **Example** ```js tinymce.init({ selector: 'textarea#context-form', height: 300, setup: (editor) => { const isAnchorElement = (node) => { return node.nodeName.toLowerCase() === 'a' && node.href; } const getAnchorElement = () => { const node = editor.selection.getNode(); return isAnchorElement(node) ? node : null; }; editor.ui.registry.addContextForm('link-form', { launch: { type: 'contextformtogglebutton', icon: 'link' }, label: 'Link', predicate: isAnchorElement, initValue: () => { const elm = getAnchorElement(); return !!elm ? elm.href : ''; }, commands: [ { type: 'contextformtogglebutton', icon: 'link', tooltip: 'Link', primary: true, onSetup: (buttonApi) => { buttonApi.setActive(!!getAnchorElement()); const nodeChangeHandler = () => { buttonApi.setActive(!editor.readonly && !!getAnchorElement()); }; editor.on('nodechange', nodeChangeHandler); return () => editor.off('nodechange', nodeChangeHandler) }, onAction: (formApi) => { const value = formApi.getValue(); console.log('Save link clicked with value: ' + value); formApi.hide(); } }, { type: 'contextformtogglebutton', icon: 'unlink', tooltip: 'Remove link', active: false, onAction: (formApi) => { console.log('Remove link clicked'); formApi.hide(); } } ] }); }, content_style: 'body { font-family:Helvetica,Arial,sans-serif; font-size:16px }' }); ``` ## 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.