How to configure the Autocompleter display

A major part of finding information is the text autocomplete Google has worked on and refined in their search engine. For rich text editors, autocomplete can help users enter common information quickly.

When reading over the TinyMCE Autocompleter documentation, you can see the AutocompleteItem and CardMenuItems API functions. These two items make up the last step in the API sequence.

When users first type in the trigger character, this creates an event. The Autocompleter API matches the character, fetches the results, and displays the results. Because the fetch function returns a promise, the sequence is asynchronous.

Until recently, the only option available was AutocompleteItem. This function produced a basic, fly out dialog box showing autocomplete options for the user to select with either a mouse or keyboard:

It wasn’t until we gathered user feedback, that our engineering team developed the CardMenuItem option.

Why we improved the Autocompleter: customer feedback

The change began In late 2020. Our product development staff began to notice a pattern in customer feedback on the Autocompleter API. Questions kept coming up again and again: “could we customise the dialog?” or “Is there any way to show more information when the Autocompleter displays items?”.

We listened, and took on the feedback. This is where the CardMenuItem function came from and the new display was released in early 2021.

How to adapt and configure your Autocompleter

We’ve written before about slash commands, which use the Autocompleter API. What this guide explains is the essentials of modifying the Autocompleter, changing the appearance of autocomplete information with the CardMenuItems. This is useful if you need to change how the Autocompleter returns and displays results to end users, for example, showing usernames, profile images, or further key details about any autocomplete item.

Changing the Autocompleter content displayed

By changing to the CardMenuItem display option, you can increase the amount of information displayed to your application or website user when they type in the trigger character.

The interactive examples provided in the TinyMCE documentation demonstrates this change. When typing the trigger character to view the list of special characters, more information about the characters appears:

There are a number of values you can change to adjust how the CardMenuItem displays information:

• Change the direction of the display from a horizontal list to a vertical one
• Adjusting the number of columns displayed
• Including a visual component, such as an icon or an image.

Changing the direction of content displayed

The following sections assume you have set up a AutocompleteItem configuration in your rich text editor html, and can adjust the JavaScript to use the CardMenuItem, or that you can access and test out the interactive example provided in the TinyMCE Autocompleter documentation.

If the vertical display of the CardMenuItem is not a good fit, you can change to a horizontal display:

1. Navigate to the cardcontainer array under the 'CardMenuItem' function.
2. Include the alignment, and include the horizontal display option.
3. Specify the alignment of the display to either left or right:

/**
* 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', //change from autocompleteitem to cardmenuitem
          value: char.value,
          label: char.text,
          items: [ //include the items array
                {
                  type: 'cardcontainer', //include the cardcontainer key value
                  direction: 'horizontal', //changed from vertical 
                  align: 'right', // specify the alignment
                  items: [
                    { … }

4. Adjust the number of columns to display under the editor.ui.registry.addAutocompleter component if needed:

editor.ui.registry.addAutocompleter('specialchars_cardmenuitems', {
     ch: ':',
     minChars: 1,
     columns: 5, //changed from one to five

5. Save the changes, and then test the changes by opening your HTML file in a browser:

Depending on your use case, the horizontal display can be an viable alternative to configure.

Including an icon or image

Adding an image or icon component means including CardImage component within the CardMenuItem component. It also requires including a link to the source image you would like to display.

1. Set up the CardImage component directly after the CardText component. Specify the char.src variable, and some alt text.

{
    type: 'cardimage',
    src: char.src, //add a char.src component to add an image to the card item.
    alt: 'a random unsplash image', //include the alt text
}

2. Navigate to the top of the JavaScript content in the documentation demo where a variable called “SpecialChars” resides. In the documentation demo, this is a collection of special characters (such as “#” and “$”). To test out the image component, change the example to include a “src” element with a link to an image file:

var specialChars = [
  {
    text: "email one: ",
    value: " email1@address",
    src: "https://source.unsplash.com/user/leahhetteberg/40x60",
  },
  {
    text: "email two: ",
    value: " email2@address",
    src: "https://source.unsplash.com/user/nathanael240606/40x60",
  },
  {
    text: "email three: ",
    value: " email3@address",
    src: "https://source.unsplash.com/user/klim11/40x60",
  },
  {
    text: "email four: ",
    value: " email4@address",
    src: "https://source.unsplash.com/user/verdurousar/40x60",
  },
];

The special characters have shifted to become a list of email addresses, and a random image file selected from four different unsplash.com accounts.

3. Save the changes, and then test the changes by opening your HTML file in a browser:

Next steps for your Rich Text Editor

After adding in the image or icon selection, you can experiment with the horizontal or vertical values, and the number of columns to display until you shape the ideal card item for your project.

You can sign up for an API key  to further test out the different alignment, image, and icon display options for yourself in your own projects.