This component is used to provide autocompletion support for a child input component.

Props

The following props are used to control the behavior of the component.

record

The rich text value object the autocompleter is being applied to.

• Required: Yes
• Type: RichTextValue

onChange

A function to be called when an option is selected to insert into the existing text.

• Required: Yes
• Type: ( value: string ) => void

onReplace

A function to be called when an option is selected to replace the existing text.

• Required: Yes
• Type: ( values: RichTextValue[] ) => void

completers

An array of all of the completers to apply to the current element.

• Required: Yes
• Type: Array< WPCompleter >

contentRef

A ref containing the editable element that will serve as the anchor for Autocomplete‘s Popover.

• Required: Yes
• MutableRefObject< HTMLElement | undefined >

children

A function that returns nodes to be rendered within the Autocomplete.

• Required: Yes
• Type: Function

isSelected

Whether or not the Autocomplete component is selected, and if its Popover should be displayed.

• Required: Yes
• Type: Boolean

Autocompleters

Autocompleters enable us to offer users options for completing text input. For example, Gutenberg includes a user autocompleter that provides a list of user names and completes a selection with a user mention like @mary.

Each completer declares:

• Its name.
• The text prefix that should trigger the display of completion options.
• Raw option data.
• How to render an option’s label.
• An option’s keywords, words that will be used to match an option with user input.
• What the completion of an option looks like, including whether it should be inserted in the text or used to replace the current block.

In addition, a completer may optionally declare:

• A class name to be applied to the completion menu.
• Whether it should apply to a specified text node.
• Whether the completer applies in a given context, defined via a Range before and a Range after the autocompletion trigger and query.

The Completer Interface

name

The name of the completer. Useful for identifying a specific completer to be overridden via extensibility hooks. Each completer should have a unique name.

• Type: String
• Required: Yes

options

The raw options for completion. May be an array, a function that returns an array, or a function that returns a promise for an array.

Options may be of any type or shape. The completer declares how those options are rendered and what their completions should be when selected.

• Type: Array|Function
• Required: Yes

triggerPrefix

The string prefix that should trigger the completer. For example, Gutenberg’s block completer is triggered when the ‘/’ character is entered.

• Type: String
• Required: Yes

getOptionLabel

A function that returns the label for a given option. A label may be a string or a mixed array of strings, elements, and components.

• Type: Function
• Required: Yes

getOptionKeywords

A function that returns the keywords for the specified option.

• Type: Function
• Required: No

isOptionDisabled

A function that returns whether or not the specified option should be disabled. Disabled options cannot be selected.

• Type: Function
• Required: No

getOptionCompletion

A function that takes an option and responds with how the option should be completed. By default, the result is a value to be inserted in the text. However, a completer may explicitly declare how a completion should be treated by returning an object with action and value properties. The action declares what should be done with the value.

There are currently two supported actions:

• “insert-at-caret” – Insert the value into the text (the default completion action).
• “replace” – Replace the current block with the block specified in the value property.

allowContext

A function that takes a Range before and a Range after the autocomplete trigger and query text and returns a boolean indicating whether the completer should be considered for that context.

• Type: Function
• Required: No

className

A class name to apply to the autocompletion popup menu.

• Type: String
• Required: No

isDebounced

Whether to debounce the autocompleter. This setting only affects the options argument; it is ignored by the useItems.

• Type: Boolean
• Required: No

Usage

The Autocomplete component is not currently intended to be used as a standalone component. It is used by other packages to provide autocompletion support for the block editor.

The block editor provides a separate, wrapped version of Autocomplete that supports the addition of custom completers via a filter.

To implement your own completer in the block editor you will:
1. Define the completer
2. Write a callback that will add your completer to the list of existing completers
3. Add a filter to the editor.Autocomplete.completers hook that will call your callback

The following example will add a contrived “fruits” autocompleter to the block editor. Note that in the callback it’s possible to limit this new completer to a specific block type. In this case, our “fruits” completer will only be available from the “core/paragraph” block type.

( function () {
    // Define the completer
    const fruits = {
        name: 'fruit',
        // The prefix that triggers this completer
        triggerPrefix: '~',
        // The option data
        options: [
            { visual: '🍎', name: 'Apple', id: 1 },
            { visual: '🍊', name: 'Orange', id: 2 },
            { visual: '🍇', name: 'Grapes', id: 3 },
            { visual: '🥭', name: 'Mango', id: 4 },
            { visual: '🍓', name: 'Strawberry', id: 5 },
            { visual: '🫐', name: 'Blueberry', id: 6 },
            { visual: '🍒', name: 'Cherry', id: 7 },
        ],
        // Returns a label for an option like "🍊 Orange"
        getOptionLabel: ( option ) => `${ option.visual } ${ option.name }`,
        // Declares that options should be matched by their name
        getOptionKeywords: ( option ) => [ option.name ],
        // Declares that the Grapes option is disabled
        isOptionDisabled: ( option ) => option.name === 'Grapes',
        // Declares completions should be inserted as abbreviations
        getOptionCompletion: ( option ) => option.visual,
    };

    // Define a callback that will add the custom completer to the list of completers
    function appendTestCompleters( completers, blockName ) {
        return blockName === 'core/paragraph'
            ? [ ...completers, fruits ]
            : completers;
    }

    // Trigger our callback on the `editor.Autocomplete.completers` hook
    wp.hooks.addFilter(
        'editor.Autocomplete.completers',
        'fruit-test/fruits',
        appendTestCompleters,
        11
    );
} )();

Finally, enqueue your JavaScript file as you would any other, as in the following plugin example:

<?php
/**
 * Plugin Name: Fruit Autocompleter
 * Plugin URI: https://github.com/WordPress/gutenberg
 * Author: Gutenberg Team
 */

/**
 * Registers a custom script for the plugin.
 */
function enqueue_fruit_autocompleter_plugin_script() {
    wp_enqueue_script(
        'fruit-autocompleter',
        plugins_url( '/index.js', __FILE__ ),
        array(
            'wp-hooks',
        ),
    );
}

add_action( 'init', 'enqueue_fruit_autocompleter_plugin_script' );