Autocomplete Edit

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


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.

Top ↑

The Completer Interface

Top ↑


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

  • Type: String
  • Required: Yes

Top ↑


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

Top ↑


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

Top ↑


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

Top ↑


A function that returns the keywords for the specified option.

  • Type: Function
  • Required: No

Top ↑


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

  • Type: Function
  • Required: No

Top ↑


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.

Top ↑


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

Top ↑


A class name to apply to the autocompletion popup menu.

  • Type: String
  • Required: No

Top ↑


Whether to apply debouncing for the autocompleter. Set to true to enable debouncing.

  • Type: Boolean
  • Required: No

Top ↑


The following is a contrived completer for fresh fruit.

import { Autocomplete } from '@wordpress/components';

const MyAutocomplete = () => {
    const autocompleters = [
            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 },
            // Returns a label for an option like "🍊 Orange"
            getOptionLabel: ( option ) => (
                    <span className="icon">{ option.visual }</span>
                    { }
            // Declares that options should be matched by their name
            getOptionKeywords: ( option ) => [ ],
            // Declares that the Grapes option is disabled
            isOptionDisabled: ( option ) => === 'Grapes',
            // Declares completions should be inserted as abbreviations
            getOptionCompletion: ( option ) => (
                <abbr title={ }>{ option.visual }</abbr>

    return (
            <Autocomplete completers={ autocompleters }>
                { ( { isExpanded, listBoxId, activeId } ) => (
                        aria-expanded={ isExpanded }
                        aria-owns={ listBoxId }
                        aria-activedescendant={ activeId }
                ) }
            <p>Type ~ for triggering the autocomplete.</p>