<div class="input">
  <input type="text" />
</div>

A styled input element. Styling of the element is determined by the Color Combination utility it is nested under.

<form class="input-search">
  <input id="search-field" name="s" placeholder="Search" type="text" />
  <button class="input__btn" type="submit">
    <svg class="icon icon-ui">
      <use xlink:href="#feather-search"></use>
    </svg>
  </button>
</form>

The graphics for the search button are included in the feather sprite that needs to be inlined in the DOM to appear.

<form class="input-search h5">
  <input class="border-4" id="search-field" name="s" placeholder="Search" type="text" />
  <button class="input__btn-large" type="submit">
    <svg class="icon icon-ui">
      <use xlink:href="#feather-search"></use>
    </svg>
  </button>
</form>

The graphics for the search button are included in the feather sprite that needs to be inlined in the DOM to appear.

<div class="input input-autocomplete">
  <input aria-autocomplete="both" aria-describedby="input-autocomplete__instructions-0" aria-expanded="false" aria-owns="input-autocomplete__options" autocomplete="off" data-js="input-autocomplete__input" type="text" />
  <div aria-live="polite" class="sr-only" id="input-autocomplete__instructions-0"></div>
</div>

The Autocomplete Input Element uses JavaScript to provide an accessible and selectable list of suggested terms as a user types into the field.

The suggested terms are passed to the autocomplete class on instantiation and can be updated on the fly with new terms. Terms are displayed in order by relevance and synonym mapping (see usage details below), Additionally the function is miss-spelling tolerant.

Markup

<div class="input-autocomplete">
  <input aria-autocomplete="both" aria-describedby="input-autocomplete__instructions-0" aria-expanded="false" aria-owns="input-autocomplete__options" autocomplete="off" data-js="input-autocomplete__input" type="text" />
  <div aria-live="polite" class="sr-only" id="input-autocomplete__instructions-0"></div>
</div>

Note: You can add the data-persist-dropdown='true' attribute to the input element for testing. The attribute will make the dropdown persist after the input is no longer in focus.

Global Script

To use the Autocomplete Input in the global NYCO Patterns script use the following code:

const nyco = new NYCO();

nyco.autocomplete({
  options: [
    ['Bronx'], ['Queens']
  ]
});

This function will instantiate the autocomplete with the provided options and attach the event listener to an input element with the default selector [data-js='input-autocomplete__input'] (see markup details in the example above ).

Below is an advanced configuration that passes a callback to the “selected” method of the autocomplete class. This callback is executed after a user has selected an option and the input value has been set. It will pass the selected value (String) as the first argument and the autocomplete class (Object) as the second.

var autocomplete = nyco.autocomplete({
  selected: function(value, autocomplete) {
    console.dir('Selected ' + value + '!');
  }
});

Updating Options

Below is an example of using the options setter to update the options after the class has been instantiated.

autocomplete.options([
  ['Bronx'], ['Queens'], ['Brooklyn'], ['Staten Island'], ['Manhattan']
]);

Providing Synonyms

Each option can be provided with a list of synonyms that will score the option higher as the user types. Try it out in the example above by typing “Hunts Point” in the input. The option “Bronx” will be listed before all other options. This method can be used to provide common terms for specific search terms that exist in your site.

autocomplete.options([
  ['Bronx', 'Hunts Point', 'Arthur Avenue', 'Riverside', 'Mott Haven'],
  ['Queens', 'Corona', 'East Elmhurst', 'Forest Hills', 'Fresh Pond'],
  ['Brooklyn', 'Flatbush', 'Bay Ridge', 'DUMBO', 'Williamsburg'],
  ['Staten Island', 'South Beach', 'Fort Wadsworth', 'Todt Hill', 'Great Kills'],
  ['Manhattan', 'Lower', 'Midtown', 'Chinatown', 'SoHo']
]);

Providing Strings

The list of strings below are used for screen reader accessibility by default. They can be overridden using the .strings method and passing an object of new strings. For the options strings, a dynamic variable string (denoted by {{ }} below) is provided and rendered in the output of the string. This method can be used to provide a localized set of strings.

autocomplete.strings({
  'DIRECTIONS_TYPE': 'Start typing to generate a list of potential input options',
  'DIRECTIONS_REVIEW': 'Keyboard users can use the up and down arrows to review options and press enter to select an option',
  'OPTION_AVAILABLE': '{{ NUMBER }} options available',
  'OPTION_SELECTED': '{{ VALUE }} selected'
});

Configuration

The autocomplete class accepts an object {} with two properties: selector and options.

ES Module

The nyco.autocomplete() method is a wrapper around the Patterns Script autocomplete utility which is included as a dependency of this project. The utility can be imported as an ES module and instantiated separately.

import autocomplete from '@nycopportunity/pttrn-scripts/src/autocomplete/autocomplete';

new autocomplete({
  options: [
    ['Bronx'], ['Queens']
  ]
});

Accessibility

Accessibility is supported through ARIA attributes that will prompt the user on how to use the dropdown list. Screen readers will also announce the list of options in the dropdown as the user navigates them with the keyboard. To maintain the elements accessibility, the accessibility utility should be used and the appropriate ARIA attributes applied to the element (see markup section).