ba-input-typeahead

ba-input-typeahead is the combination of a textfield and an associated dropdown that allows the user to filter a list when selecting an option.

 Figma GitHub Storybook

Presenting users with a long list of options (typically 10 or more) that can be filtered by typing in the text field.

For shorter lists of items where filtering is not needed, typically under 10 items. For that use <ba-select>

Always use the label attribute to give a meaningful label to the field.

Further reading:

Disabled form elements are not supported in BAgel because they create accessibility challenges, such as preventing keyboard navigation, confusing screen reader users, and reducing visual clarity for those with impairments

Further reading:

Placeholders on inputs are not supported in BAgel because they create accessibility challenges, such as failing to provide persistent labels for screen readers, reducing color contrast for users with visual impairments, and causing confusion for those with cognitive difficulties.

If you would like to add a infomations to help the user fill the input, you can use the hint-text attribute.

Further reading:

The component is based on the combobox-autocomplete-list pattern by the web accessibility initiative using a combination of the combobox and list box roles to achieve the typeahead functionality.

More information on the roles can be found below:

These are issues that have been reported to Chromium and Webkit that affect the usability of the this component when using talkback and voiceover screen readers

Not able to access ARIA Listbox items with TalkBack

This results in talkback users not being able to select options from the dropdown list.

https://bugs.chromium.org/p/chromium/issues/detail?id=1425494#c4

Voiceover issues with aria-activedescendant

Voiceover users are not able to perceive the available options and announces wrong instructions to interact with the listbox

https://bugs.webkit.org/show_bug.cgi?id=231724
Element State Key press Behaviour
Previous element in DOM Previous element in DOM has focus Tab <input> in shadow DOM gets focus
<input> in shadow button in shadow has focus Cntrl, Down Arrow or Spacebar Opens the suggestion list
<input> in shadow suggestion list open Arrow Keys Navigates the suggestion list
<input> in shadow suggestion list open Escape Closes the suggestion list
suggestions list in shadow item in list highlighted Enter or Tab Selects the highlighted item from the suggestion list

Code

Properties & Attributes

Property Attribute Description Type Default
hintText hint-text Hint text to show above the input string | undefined undefined
invalid invalid Whether the input is invalid or not boolean | undefined false
label (required) label The label for the input string undefined
maxInputLength max-input-length Maximum input length after which typeahead functionality will be disabled number | undefined 0
minInputLength min-input-length Minimum input length before typeahead functionality is enabled number | undefined 1
name name The name of the input string | undefined undefined
noMatch no-match Show did you mean text boolean | undefined false
noMatchErrorMessage no-match-error-message No match error message string | undefined undefined
noMatchText no-match-text No match text string | undefined undefined
required required If `true`, the user must fill in a value before submitting a form. boolean | undefined false
suggestions suggestions Search suggestions for the typeahead field Suggestion[] | string | undefined ''
value value The value of the input. null | string | undefined ''
Example of an array of suggestions
  [
    {
      "value": "LON",
      "text": "London, London (All Airports) (LON), United Kingdom"
    },
    {
      "value": "LCY",
      "text": "London City Airport (LCY) United Kingdom"
    },
    {
      "value": "LGW",
      "text": "London Gatwick (LGW) United Kingdom"
    },
    {
      "value": "LHR",
      "text": "London Heathrow (LHR) United Kingdom"
    },
    {
      "value": "LTN",
      "text": "London Luton (LTN) United Kingdom"
    },
  ]

Events

Event Description Type
baBlur Emitted when the input loses focus. CustomEvent<void>
baFocus Emitted when the input has focus. CustomEvent<void>
baOnInput Emitted when a keyboard input occurred. CustomEvent<InputChangeEventDetail>
baOnSuggestionSelect Emitted when the typeahead suggestion is selected CustomEvent<any>

Methods

isValid() => Promise<boolean>

An exposed method for triggering the inputs required validation

reset() => Promise<void>

Resets the input back to its initial value

Returns

Type: Promise<void>

getData() => Promise<Suggestion>

Returns both the currently selected data and the user entered value

If the user has not selected a suggestion, or edits the value after selecting, the selectedSuggestion will be an empty object

Returns

Type: Promise<Suggestion>

Slots

Slot Description Permitted elements
"error" Element will be rendered in the error slot <p>

Parent components

ba-input-typeahead can be slotted into:

Usage

To use <ba-input-typeahead> pass the suggestions and other required props. When a user starts to enter text into the input, after the minInputLength has been reached the dropdown will show. Once a option has been selected it will be emitted with the baOnSuggestionSelect event.

basic Usage
    <ba-input-typeahead
      id="ba-input-typeahead"
      value="London, City Airport (LCY), United Kingdom"
      label="From"
      hint-text="Type 3 letters"
      suggestions="[
          {
            value: 'LON',
            text: 'London, London (All Airports) (LON), United Kingdom'
          },
          {
            value: 'LCY',
            text: 'London City Airport (LCY) United Kingdom'
          },
          {
            value: 'LGW',
            text: 'London Gatwick (LGW) United Kingdom'
          },
          {
            value: 'LHR',
            text: 'London Heathrow (LHR) United Kingdom'
          },
          {
            value: 'LTN',
            text: 'London Luton (LTN) United Kingdom'
          },
          {
            value: 'STN',
            text: 'London Stansted (STN) United Kingdom'
          },
          {
            value: 'LDY',
            text: 'Londonderry Londonderry (LDY) United Kingdom'
          },
          {
            value: 'LGB',
            text: 'Long Beach (CA) Long Beach (CA) (LGB) USA'
          },
          {
            value: 'GGG',
            text: 'Longview East Texas Regional (TX) (GGG) USA'
          },
          {
            value: 'LYR',
            text: 'Longyearbyen Svalbard (LYR) Norway'
          },
          {
            value: 'CGQ',
            text: 'Changchun Longjia Intl (CGQ) China'
          },
          {
            value: 'ELS',
            text: 'East London East London (ELS) South Africa'
          }
        ]"
    >
    </ba-input-typeahead>

  <script>
    document.addEventListener('baOnSuggestionSelect', function(event) {
        const typeahead = document.getElementById('ba-input-typeahead')
        if (typeahead.hasAttribute('invalid')) {
          typeahead.removeAttribute('invalid')
        }
    })
  </script>

No match

If what the user has typed into the input does not match any items from the dropdown. A message can be shown by adding the no-match prop, and also adding text to the no-match-error-message and no-match-text props. Validation to check if the inputted value does not match any of the suggestions is not done by the component and must be outside of it.

No Match
    <ba-input-typeahead
      id="ba-input-typeahead"
      value="London, City Airport (LCY), United Kingdom"
      label="From"
      no-match
      no-match-error-message="We don't recognise the value"
      no-match-text="Did you mean:"
      suggestions="[
          {
            value: 'LON',
            text: 'London, London (All Airports) (LON), United Kingdom'
          },
          {
            value: 'LCY',
            text: 'London City Airport (LCY) United Kingdom'
          },
          {
            value: 'LGW',
            text: 'London Gatwick (LGW) United Kingdom'
          },
          {
            value: 'LHR',
            text: 'London Heathrow (LHR) United Kingdom'
          },
          {
            value: 'LTN',
            text: 'London Luton (LTN) United Kingdom'
          },
          {
            value: 'STN',
            text: 'London Stansted (STN) United Kingdom'
          },
          {
            value: 'LDY',
            text: 'Londonderry Londonderry (LDY) United Kingdom'
          },
          {
            value: 'LGB',
            text: 'Long Beach (CA) Long Beach (CA) (LGB) USA'
          },
          {
            value: 'GGG',
            text: 'Longview East Texas Regional (TX) (GGG) USA'
          },
          {
            value: 'LYR',
            text: 'Longyearbyen Svalbard (LYR) Norway'
          },
          {
            value: 'CGQ',
            text: 'Changchun Longjia Intl (CGQ) China'
          },
          {
            value: 'ELS',
            text: 'East London East London (ELS) South Africa'
          }
        ]"
        ></ba-input-typeahead>
</figure>
GitHub Storybook Figma library Version 3 release guide Release history BAgel helper QA process