WordPress.org

Autocomplete Edit

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

Autocompleters 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 The Completer Interface

name name

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

  • Type: String
  • Required: Yes

Top ↑

options 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

Top ↑

triggerPrefix 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

Top ↑

getOptionLabel 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

Top ↑

getOptionKeywords getOptionKeywords

A function that returns the keywords for the specified option.

  • Type: Function
  • Required: No

Top ↑

isOptionDisabled isOptionDisabled

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

  • Type: Function
  • Required: No

Top ↑

getOptionCompletion 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.

Top ↑

allowNode allowNode

A function that takes a text node and returns a boolean indicating whether the completer should be considered for that node.

  • Type: Function
  • Required: No

Top ↑

allowContext 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

Top ↑

className className

A class name to apply to the autocompletion popup menu.

  • Type: String
  • Required: No

Top ↑

isDebounced isDebounced

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

  • Type: Boolean
  • Required: No

Top ↑

Usage Usage

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>
                    <span className="icon" >{ option.visual }</span>{ option.name }
                </span>
            ),
            // 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 => (
                <abbr title={ option.name }>{ option.visual }</abbr>
            ),
        }
    ];

    return (
        <div>
            <Autocomplete completers={ autocompleters }>
                { ( { isExpanded, listBoxId, activeId } ) => (
                    <div
                        contentEditable
                        suppressContentEditableWarning
                        aria-autocomplete="list"
                        aria-expanded={ isExpanded }
                        aria-owns={ listBoxId }
                        aria-activedescendant={ activeId }
                    >
                    </div>
                ) }
            </Autocomplete>
            <p>Type ~ for triggering the autocomplete.</p>
        </div>
    );
};
Skip to toolbar