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
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
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
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
getOptionKeywords getOptionKeywords
A function that returns the keywords for the specified option.
- Type:
Function
- Required: No
isOptionDisabled isOptionDisabled
A function that returns whether or not the specified option should be disabled. Disabled options cannot be selected.
- Type:
Function
- Required: No
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.
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
className className
A class name to apply to the autocompletion popup menu.
- Type:
String
- Required: No
isDebounced isDebounced
Whether to apply debouncing for the autocompleter. Set to true to enable debouncing.
- Type:
Boolean
- Required: No
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> ); };