Title: Autocomplete Published: March 9, 2021 Last modified: April 8, 2026 --- # Autocomplete ## In this article * [Props](https://developer.wordpress.org/block-editor/reference-guides/components/autocomplete/?output_format=md#props) - [record](https://developer.wordpress.org/block-editor/reference-guides/components/autocomplete/?output_format=md#record) - [onChange](https://developer.wordpress.org/block-editor/reference-guides/components/autocomplete/?output_format=md#onchange) - [onReplace](https://developer.wordpress.org/block-editor/reference-guides/components/autocomplete/?output_format=md#onreplace) - [completers](https://developer.wordpress.org/block-editor/reference-guides/components/autocomplete/?output_format=md#completers) - [contentRef](https://developer.wordpress.org/block-editor/reference-guides/components/autocomplete/?output_format=md#contentref) - [children](https://developer.wordpress.org/block-editor/reference-guides/components/autocomplete/?output_format=md#children) - [isSelected](https://developer.wordpress.org/block-editor/reference-guides/components/autocomplete/?output_format=md#isselected) * [Autocompleters](https://developer.wordpress.org/block-editor/reference-guides/components/autocomplete/?output_format=md#autocompleters) - [The Completer Interface](https://developer.wordpress.org/block-editor/reference-guides/components/autocomplete/?output_format=md#the-completer-interface) * [Usage](https://developer.wordpress.org/block-editor/reference-guides/components/autocomplete/?output_format=md#usage) [ Back to top](https://developer.wordpress.org/block-editor/reference-guides/components/autocomplete/?output_format=md#wp--skip-link--target) This component is used to provide autocompletion support for a child input component. ## 󠀁[Props](https://developer.wordpress.org/block-editor/reference-guides/components/autocomplete/?output_format=md#props)󠁿 The following props are used to control the behavior of the component. ### 󠀁[record](https://developer.wordpress.org/block-editor/reference-guides/components/autocomplete/?output_format=md#record)󠁿 The rich text value object the autocompleter is being applied to. * Required: Yes * Type: `RichTextValue` ### 󠀁[onChange](https://developer.wordpress.org/block-editor/reference-guides/components/autocomplete/?output_format=md#onchange)󠁿 A function to be called when an option is selected to insert into the existing text. * Required: Yes * Type: `( value: string ) => void` ### 󠀁[onReplace](https://developer.wordpress.org/block-editor/reference-guides/components/autocomplete/?output_format=md#onreplace)󠁿 A function to be called when an option is selected to replace the existing text. * Required: Yes * Type: `( values: RichTextValue[] ) => void` ### 󠀁[completers](https://developer.wordpress.org/block-editor/reference-guides/components/autocomplete/?output_format=md#completers)󠁿 An array of all of the completers to apply to the current element. * Required: Yes * Type: `Array< WPCompleter >` ### 󠀁[contentRef](https://developer.wordpress.org/block-editor/reference-guides/components/autocomplete/?output_format=md#contentref)󠁿 A ref containing the editable element that will serve as the anchor for `Autocomplete`‘ s `Popover`. * Required: Yes * `MutableRefObject< HTMLElement | undefined >` ### 󠀁[children](https://developer.wordpress.org/block-editor/reference-guides/components/autocomplete/?output_format=md#children)󠁿 A function that returns nodes to be rendered within the Autocomplete. * Required: Yes * Type: `Function` ### 󠀁[isSelected](https://developer.wordpress.org/block-editor/reference-guides/components/autocomplete/?output_format=md#isselected)󠁿 Whether or not the Autocomplete component is selected, and if its `Popover` should be displayed. * Required: Yes * Type: `Boolean` ## 󠀁[Autocompleters](https://developer.wordpress.org/block-editor/reference-guides/components/autocomplete/?output_format=md#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](https://developer.wordpress.org/block-editor/reference-guides/components/autocomplete/?output_format=md#the-completer-interface)󠁿 #### 󠀁[name](https://developer.wordpress.org/block-editor/reference-guides/components/autocomplete/?output_format=md#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](https://developer.wordpress.org/block-editor/reference-guides/components/autocomplete/?output_format=md#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](https://developer.wordpress.org/block-editor/reference-guides/components/autocomplete/?output_format=md#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](https://developer.wordpress.org/block-editor/reference-guides/components/autocomplete/?output_format=md#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](https://developer.wordpress.org/block-editor/reference-guides/components/autocomplete/?output_format=md#getoptionkeywords)󠁿 A function that returns the keywords for the specified option. * Type: `Function` * Required: No #### 󠀁[isOptionDisabled](https://developer.wordpress.org/block-editor/reference-guides/components/autocomplete/?output_format=md#isoptiondisabled)󠁿 A function that returns whether or not the specified option should be disabled. Disabled options cannot be selected. * Type: `Function` * Required: No #### 󠀁[getOptionCompletion](https://developer.wordpress.org/block-editor/reference-guides/components/autocomplete/?output_format=md#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](https://developer.wordpress.org/block-editor/reference-guides/components/autocomplete/?output_format=md#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](https://developer.wordpress.org/block-editor/reference-guides/components/autocomplete/?output_format=md#classname)󠁿 A class name to apply to the autocompletion popup menu. * Type: `String` * Required: No #### 󠀁[isDebounced](https://developer.wordpress.org/block-editor/reference-guides/components/autocomplete/?output_format=md#isdebounced)󠁿 Whether to debounce the autocompleter. This setting only affects the `options` argument; it is ignored by the `useItems`. * Type: `Boolean` * Required: No ## 󠀁[Usage](https://developer.wordpress.org/block-editor/reference-guides/components/autocomplete/?output_format=md#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. ```javascript ( 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