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 ↑

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>
    );
};