Keyword suggestions

search-input and search-box can suggest keywords while the visitor types. The suggestions come from Search API Autocomplete, through the Search API Decoupled Autocomplete submodule, which registers each endpoint as an autocomplete search. Search Web Components has no suggester of its own. What is suggested, how many suggestions, and the minimum length are the search's settings.

Enable suggestions on an endpoint

1. Install Search API Autocomplete and enable Search API Decoupled Autocomplete (search_api_decoupled_autocomplete).
2. On the index's Autocomplete tab, under Configuration › Search and metadata › Search API, enable the search named after the endpoint and click Edit to pick its suggesters and set its options.
3. On the endpoint's edit form, under Roles that get suggestions, check Anonymous user and Authenticated user, and click Save. The field shows once the endpoint has an enabled autocomplete search. A role that is not checked gets the plain input.

The blocks

• Search Input suggests keywords as soon as the endpoint has an enabled autocomplete search, from the URL the endpoint response carries. To keep a plain input, check Turn off keyword suggestions.
• Search Box is outside a search root, so it names the endpoint under Suggestions. The list offers the endpoints with an enabled autocomplete search.

Both blocks have three A11y: texts for the list: its name, and what screen readers hear when it opens.

Twig and Drupal Canvas

The props, on search_web_components:search-input and search_web_components:search-box:

Prop	Default	What it does
noSuggestions	false	Turns suggestions off. The input stays a plain text field.
autocompleteUrl	empty	The URL suggestions are requested from, with the keywords added as q. On search-input, the endpoint response's URL is used when the prop is empty.
autocompleteMinLength	2	How many characters the visitor types before suggestions are requested.
autocompleteDelay	300	The pause in typing, in milliseconds, before suggestions are requested.
suggestionsLabelText	Suggestions	The accessible name of the list.
suggestionsCountText	@count suggestions available	What screen readers hear when the list opens.
oneSuggestionText	1 suggestion available	What screen readers hear when the list opens with one suggestion.

The suggestions URL of an endpoint is /search_api_autocomplete/<endpoint id>.

How the list works

• The list opens when suggestions come back for what was typed, and closes when none do, when the input is emptied, when focus leaves the input, and on submit.
• Down and Up open the list and move the highlight. From the last suggestion, Down returns to the input. The input keeps its text while the highlight moves. Left, Right, Home, and End move the caret and return the highlight to the input.
• Enter searches the highlighted suggestion. Without one, Enter searches what was typed. Escape closes the list.
• A suggestion that goes to a page, e.g., a content item the suggester matched, has a link class and takes the visitor there when picked.
• The suggestion labels are the HTML the search answers with, e.g., the typed part in a <strong> element and a result count.

The input follows the W3C editable combobox pattern. For the pattern and what the input sets, see Accessibility.

Styling

No CSS ships for the list. The classes, with search-input or search-box as the prefix:

• <prefix>-suggestions on the list, with open while it is open. The list is hidden while closed.
• <prefix>-suggestion on each suggestion, with focused on the highlighted one.
• <prefix>-suggestion-link on a suggestion that goes to a page.

For how the components are styled, see Styling.

Decoupled use

Set autocompleteUrl on the element, or send swc_autocomplete.url in the search response for search-input. The URL is requested with GET and q=<keywords>, and answers a list of {value, label, url?}. To suggest from another API, override the request hooks of the element, _buildSuggestionsRequest(), _fetchSuggestions(), and _mapSuggestions(), the way Searching another API does for the search root.