Question

Overview and use case

An autocompleter enables users to quickly find and select from a pre-populated list of values as they type, leveraging searching and filtering. It provides suggestions to insert while the user is typing into the content. For example, with the charmap plugin enabled, typing :amp should show the ampersand item in the menu. Pressing esc should close the autocomplete menu.

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	Required	The character to trigger the autocompleter.
fetch	(pattern: string, maxResults: number) => Promise<AutocompleterItem[]>	Required	A function that is passed the current matched text pattern and the maximum number of expected results. 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).

The fetch function is called whenever the trigger char is pressed and the matches predicate returns true. It is a function that takes the matched text pattern and returns a promise containing matching results. This allows for asynchronous fetching of the autocompleter items. The results should be a list of objects with the following details:

• value: Value of the item. This will be passed to the onAction callback when selected.
• text: Text to display for the item.
• icon: Name of the icon to be displayed. Must be a single unicode character or correspond to an icon in the icon pack.

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

API

Name	Value	Description
hide	() => void	Hides the autocompleter menu.

Example

This example shows how the charmap plugin adds the standard autocompleter. The autocompleter will show whenever a : character is typed plus at least one additional character.

TinyMCE HTML JS Edit on CodePen

<textarea id="autocompleter">
  <p>Type <b>:</b> below and then keep typing to reduce further matches. For example, typing <b>:amp</b> should show the ampersand item in the menu. Pressing esc should close the autocomplete menu.</p>
  <p></p>
</textarea>

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',
  height: 250,
  setup: function (editor) {
    /* An autocompleter that allows you to insert special characters */
    editor.ui.registry.addAutocompleter('specialchars', {
      ch: ':',
      minChars: 1,
      columns: 'auto',
      fetch: function (pattern) {
        var matchedChars = specialChars.filter(function (char) {
          return char.text.indexOf(pattern) !== -1;
        });

        return new tinymce.util.Promise(function (resolve) {
          var results = matchedChars.map(function (char) {
            return {
              value: char.value,
              text: char.text,
              icon: char.value
            }
          });
          resolve(results);
        });
      },
      onAction: function (autocompleteApi, rng, value) {
        editor.selection.setRng(rng);
        editor.insertContent(value);
        autocompleteApi.hide();
      }
    });
  }
});