Autocomplete

<bolt-autocomplete label="Subject" onkeyup="setOptions(this)"></bolt-autocomplete>

By default, the input will not use any of the suggested values until they are explicitly chosen (manual completion).

By setting completion to auto, the first value in the list will be selected as soon as results are displayed, and when navigating away from the input, the selected value will be chosen automatically.

<bolt-autocomplete completion="auto" label="Subject" onkeyup="setOptions(this)"></bolt-autocomplete>

A maximum of 5 results are displayed by default, but up to 10 results may be displayed using maxoptions.

<bolt-autocomplete maxoptions="10" label="Subject" onkeyup="setOptions(this)"></bolt-autocomplete>

Autocomplete suggestions are shown after 3 characters are entered by default, but a different number of characters may be specified with mincharacters.

<bolt-autocomplete mincharacters="2" label="Subject" onkeyup="setOptions(this)"></bolt-autocomplete>

<bolt-autocomplete onkeyup="setOptions(this)" label="Label">
    <bolt-contextual-help slot="help" heading="Help text heading">
        <p>Help text body content</p>
    </bolt-contextual-help>
</bolt-autocomplete>

The <bolt-autocomplete> custom element provides an interface for displaying a list of suggested items based on the text that is entered.

Filtering is not handled by <bolt-autocomplete> directly, but its value can be accessed for use in a search function. Filtered results can be passed back to the element by setting an array as options and, if desired, accompanying optionvalues.

In the demo below, the example function setOptions(element) listens for a keyup event on <bolt-autocomplete>, and passes a reference to the autocomplete element. It then searches for Wikipedia articles based on the element's value, and sets a list of matching article titles as options and corresponding article URLs as optionvalues.

<bolt-autocomplete label="Article" onkeyup="setOptions(this)"></bolt-autocomplete>

<script>

function setOptions(element){

    // Call search function
    let data = getWikiResults(element.value);

    // Parse JSON results into arrays for the info we need
    let results = data[1];
    let resultvalues = data[3];

    // Send back results
    element.options = results;
    element.optionvalues = resultvalues
}
</script>

The <bolt-autocomplete> custom element accepts the following attributes:

• completion: optional. manual (default) or auto. auto completion will automatically move focus to the first option on the list when opened, and will select the focused option when the user navigates away from the autocomplete input. manual completion will use the value the user has typed in, unless they manually click on an option from the list.
• mincharacters : optional. The number of characters that must be entered before the list of options is displayed. Default is 3.
• maxoptions : optional. 5 (default) or 10. The number of options to be displayed.
• optionheading : optional. Heading text shown above the list of options. Default is 'Suggestions'.
• options : required. An array of strings to be displayed as options.
• optionvalues : optional. An array of strings to be used as value attributes for the options. When passing options and optionvalues separately, be sure that the index of each item corresponds properly. If present, <bolt-autocomplete> will use the value of its selected option rather than its displayed text as the element's value.
• datatestinput optional property to configure the data-test value on the underlying <input> element. Default is input.

The <bolt-autocomplete> custom element emits the following events:

• bolt-option-click: emitted when any option is clicked.

Additionally, <bolt-autocomplete> allows the following attributes to be passed to the underlying <bolt-textfield> custom element:

• label: required. The label text for the input.
• instructionaltext: optional. The instructional text to display below the input. This should be used to give users additional information about the expected content in the field.
• error: optional. The error message to display after the input.
  • For slotted field error see the text field's example at text field error slot
• required: optional. If present, the field is required. Fields that are not required will show "(optional)".
• optionaltext: optional. show (default) or hide. Use to remove the "(optional)" text from non-required fields.
• disabled: optional. If present, disables rendered interactive elements.
• maxlength: optional. Maximum allowed input length.
• suffix: optional. Text displayed after the text input. Generally, this will be multiple characters, e.g. ".00".
• invalid: optional. If present, the field appears invalid.

The <bolt-autocomplete> element supports the use of <bolt-contextual-help> via the help slot placeholder. For more information and to see other options visit the contextual help page.

The following attributes are passed through to the native <input> element. Please see the MDN Input element documentation for details.

• spellcheck: optional. Defaults to false.
• autocomplete: optional. Defaults to on. Please see possible values.
• autocorrect: optional. Defaults to off.
• autocapitalize: optional. Defaults to on.
• inputmode: optional, see standard behavior

• [data-test="input"] targets primary <input> element
  • Configurable via the datatestinput property

• Instructional text underneath Autocomplete can inform users what input is expected and valid. For example, "All valid addresses are accepted."
• The number of displayed values should change dynamically based on the characters that have been entered into Autocomplete in order to display only matching values.
• An Autocomplete's listbox can display up to 10 values.
• Since Autocomplete adds functionality to a text input field, consider the following:
  1. User input can either be required or optional
  2. Contextual help, instructional text and a field error may be displayed as needed.
• If a large number of words or names can be entered into an Autocomplete's text input field, it should be combined with a Button or Link to access a complete catalog of all valid entries. For example, a list of colleges and universities that qualify its alumni for a policy premium discount.

1. The Autocomplete's listbox contains suggested values that complete or logically correspond to the characters entered in the text input field. (Values in the listbox have names that start with the characters entered in the text input field.)
2. Users may set the value of Autocomplete by selecting a value from the listbox.
3. While a value is highlighted in the listbox, and multiple values are available, the up/down arrow key may be used to highlight a value displayed above/below the highlighted value.
4. If the user does not select a value from the listbox before moving focus outside Autocomplete, the characters entered in the text input field, if any, becomes the value of Autocomplete.

1. The Autocomplete's listbox contains suggested values that complete or logically correspond to the characters entered in Autocomplete. (Values in the listbox have names that start with the characters entered in the text input field.)
2. The first matching value is automatically highlighted as selected in the listbox and can be selected with a cursor, finger or by using the Enter key.
3. While a value is highlighted in the listbox, and multiple values are available, the up/down arrow key may be used to highlight a value displayed above/below the highlighted value.
4. The automatically highlighted value becomes the value of Autocomplete when it loses focus unless the user changes the character string in the text input field.

• If it can be predicted what users intend to enter as valid input into a text input field
• Use Autocomplete when you want the user to be able to limit selections by typing.

• If it cannot be predicted what users intend to enter as valid input into a text input field.

• Consider a Select for a simple list of items.
• Consider a Select for added native mobile functionality.

• Values and headings in Autocomplete listboxs use sentence case.
• Instructional text should help users understand expected valid input, not ask for input. For example, "All valid addresses are accepted." NOT "Please enter a valid address."

• Use the Tab key to focus on the Autocomplete input field.
• Typing into the input field should enter the expanded state.
• When the suggestion list is open (expanded), use the up and down arrow keys to navigate through the suggestions. Note that the developer is responsible for dynamically filtering the suggestion list as the user types.
  • If the focus reaches the top or bottom of the list, it should wrap around to the other end, cycling back to the first or last suggestion.
• Pressing Enter should select the currently highlighted suggestion. Then it should close the dropdown (collapsed state).
• Pressing Esc should close the dropdown (collapsed state) without selecting a suggestion, then focus remains in the input field.
• When the completion attribute is set to auto, pressing Tab should move the focus out of the component. If a suggestion is highlighted, it should be automatically selected before the focus moves. With manual completion, the component should use the value entered by the user unless they explicitly click/select on an option from the provided list.

• Safari + VoiceOver will not announce expanded/collapsed when the listbox is displayed/closed.

All Bolt components have gone through accessibility testing, but please keep our accessibility guidelines in mind.