Important changes to Tiny Cloud pricing > Find out more

Autocompleter

Add a custom autocompleter to TinyMCE 5.

Contribute to this page

Overview

An autocompleter displays suggestions while the user is typing. Suggestions are shown when the trigger character is entered after a space or at the start of a new line (such as ‘ :’). Pressing the Escape key will close the autocompleter.

How to create custom autocompleters

The method for adding a custom autocompleter is in the UI Registry part of the editor API editor.ui.registry:

  • editor.ui.registry.addAutocompleter(name, configuration)

The two arguments this method take are:

  • name - A unique name for the autocompleter.
  • configuration - An object containing the user’s configuration.

Configuration options

Name Value Requirement Description
ch string (of one character) Required The character to trigger the autocompleter.
fetch (pattern: string, maxResults: number, fetchOptions: Record<string, any>) => Promise<AutocompleteItem[] | CardMenuItem[]> Required A function that is passed the current matched text pattern, the maximum number of expected results and any additional fetch options. The function should return a Promise containing matching results.
onAction (api, rng: Range, value: string) => void Required A function invoked when a fetched item is selected.
columns number or ‘auto’ Optional default: auto - The number of columns to show. If set to 1 column, then icons and text are displayed, otherwise only icons are displayed.
matches (rng: Range, text: string, pattern: string) => boolean Optional default: isStartOfWord - A predicate function that takes a range, the current text node content and the matched text content and returns a boolean indicating if the autocompleter should trigger.
maxResults number Optional default: 10 - The maximum number of results that should be fetched.
minChars number Optional default: 1 - The minimum number of characters that must be typed before the autocompleter will trigger (excluding the trigger char).
highlight array Optional When using CardMenuItems, use the highlight option to specify which CardText items to highlight the matched text pattern on.

Note: If two or more autocompleters use the same trigger character, then the fetched results will be merged together before being displayed.

Usage of fetch

The fetch function is called when the trigger char is pressed and the matches predicate returns true. The fetch function is passed the matched text pattern and returns a Promise containing matching results, specified as either AutocompleteItems or CardMenuItems. This allows for asynchronous fetching of the items. The fetchOptions parameter passed to the fetch function is by default an empty object, however using the reload API, additional options can be passed to fetch a different set of results.

There are two types of items:

AutocompleteItem

This is the standard item for the autocompleter. If no type is specified, autocompleter items are assumed to be of type AutocompleteItem.

Name Value Requirement Description
value string optional Value of the item. This will be passed to the onAction callback when selected.
text string optional Text to display for the item.
icon string optional Name of the icon to be displayed. Must be a either single unicode character or an icon from: the icon pack, a custom icon pack, or an icon added using the addIcon API.
{
  type: 'autocompleteitem',
  value: 'John Doe',
  text: 'John Doe',
  icon: 'my_icon'
}

CardMenuItem

Note: This feature is only available for TinyMCE 5.6 and later.

The CardMenuItem allows customization of layout and content. This is done by constructing an array of subcomponent specifications which will determine the structure of the final item. A classical example of this would be the need to display a “user” item containing a profile picture, a user name, and a description.

Name Value Requirement Description
items array required An array of CardItems
value string optional Value of the item. This will be passed to the onAction callback when selected.
label string optional Label of the item. Will be used for accessibility purposes.
{
  type: 'cardmenuitem',
  value: 'John Doe',
  label: 'John Doe',
  items: [ ] // array of card items
}

CardItems

CardItems are subcomponents for the CardMenuItem. Use these to construct your custom item and display relevant information to the user.

There are three types of card items:

CardContainer

A CardContainer is a layout component used to apply a layout to an array of card items.

Name Value Requirement Description
items array required An array of CardItems
direction 'vertical' or 'horizontal' optional default: horizontal - directionality of subitems
align 'left' or 'right' optional default: left - horizontal alignment of subitems
valign 'top', 'middle' or 'bottom' optional default: middle - vertical alignment of subitems
{
  type: 'cardcontainer',
  direction: 'horizontal',
  align: 'left',
  valign: 'middle',
  items: [ ... ]
}
CardText

CardText is a component for displaying text.

Name Value Requirement Description
text string required Text to display
name string optional Identifier used to reference specific CardText items. The autocompleter will use this for the text-highlight functionality.
classes array optional Array of classes to apply. Note: restrict usage to styles that won’t affect the layout, such as font-style.
{
  type: 'cardtext',
  text: 'John Doe',
  name: 'my_autocompleter_cardtext',
  classes: ['my-cardtext-class']
}
CardImage

CardImage is a component for displaying an image.

Name Value Requirement Description
src string required Image source to use
alt string required Image alt text
classes array optional Array of classes to apply. Note: restrict usage to styles that won’t affect the layout, such as border-radius.
{
  type: 'cardimage',
  src: 'profile-picture.jpeg',
  alt: 'My alt text',
  classes: ['my-cardimage-class']
}

API

Name Value Description
hide () => void Hides the autocompleter menu.
reload (fetchOptions: Record<string, any>) => void Hides the autocompleter menu and fetches new menu items. The fetchOptions will be passed to the autocompleter fetch callback.

Interactive examples

The following examples show how to create a special characters autocompleters.

Example: Standard Autocompleter

This example uses the standard autocompleter item and will show when user types the colon (:) character and at least one additional character.


var specialChars = [
  { text: 'exclamation mark', value: '!' },
  { text: 'at', value: '@' },
  { text: 'hash', value: '#' },
  { text: 'dollars', value: '$' },
  { text: 'percent sign', value: '%' },
  { text: 'caret', value: '^' },
  { text: 'ampersand', value: '&' },
  { text: 'asterisk', value: '*' }
];
tinymce.init({
  selector: 'textarea#autocompleter-autocompleteitem',
  height: 250,
  setup: function (editor) {
    var onAction = function (autocompleteApi, rng, value) {
      editor.selection.setRng(rng);
      editor.insertContent(value);
      autocompleteApi.hide();
    };

    var getMatchedChars = function (pattern) {
      return specialChars.filter(function (char) {
        return char.text.indexOf(pattern) !== -1;
      });
    };

    /* An autocompleter that allows you to insert special characters */
    editor.ui.registry.addAutocompleter('specialchars', {
      ch: ':',
      minChars: 1,
      columns: 'auto',
      onAction: onAction,
      fetch: function (pattern) {
        return new tinymce.util.Promise(function (resolve) {
          var results = getMatchedChars(pattern).map(function (char) {
            return {
              type: 'autocompleteitem',
              value: char.value,
              text: char.text,
              icon: char.value
            }
          });
          resolve(results);
        });
      }
    });
  }
});


Example: Using CardMenuItems in the Autocompleter

This example uses CardMenuItems and will show when a user types a hyphen (-) character and at least one additional character.


var specialChars = [
  { text: 'exclamation mark', value: '!' },
  { text: 'at', value: '@' },
  { text: 'hash', value: '#' },
  { text: 'dollars', value: '$' },
  { text: 'percent sign', value: '%' },
  { text: 'caret', value: '^' },
  { text: 'ampersand', value: '&' },
  { text: 'asterisk', value: '*' }
];
tinymce.init({
  selector: 'textarea#autocompleter-cardmenuitem',
  height: 250,
  setup: function (editor) {
    var onAction = function (autocompleteApi, rng, value) {
      editor.selection.setRng(rng);
      editor.insertContent(value);
      autocompleteApi.hide();
    };

    var getMatchedChars = function (pattern) {
      return specialChars.filter(function (char) {
        return char.text.indexOf(pattern) !== -1;
      });
    };

    /**
     * An autocompleter that allows you to insert special characters.
     * Items are built using the CardMenuItem.
     */
    editor.ui.registry.addAutocompleter('specialchars_cardmenuitems', {
      ch: '-',
      minChars: 1,
      columns: 1,
      highlightOn: ['char_name'],
      onAction: onAction,
      fetch: function (pattern) {
        return new tinymce.util.Promise(function (resolve) {
          var results = getMatchedChars(pattern).map(function (char) {
            return {
              type: 'cardmenuitem',
              value: char.value,
              label: char.text,
              items: [
                {
                  type: 'cardcontainer',
                  direction: 'vertical',
                  items: [
                    {
                      type: 'cardtext',
                      text: char.text,
                      name: 'char_name'
                    },
                    {
                      type: 'cardtext',
                      text: char.value
                    }
                  ]
                }
              ]
            }
          });
          resolve(results);
        });
      }
    });
  }
});


Can't find what you're looking for? Let us know.

Except as otherwise noted, the content of this page is licensed under the Creative Commons BY-NC-SA 3.0 License, and code samples are licensed under the Apache 2.0 License.