Patterns

2.3.2

Inputs

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

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

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

Error

<div><input type="number" /></div>

Number

<div class="input-currency-usd"><input type="number" /></div>

Currency

<div class="input-currency-usd error"><input type="number" /></div>

Currency Error

<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>

Input Autocomplete

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

The suggested terms are passed to the InputAutocomplete 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:

<!-- Global Script -->
<script src="dist/scripts/NycoPatterns.js"></script>

<script>
  const nyco = new NycoPatterns();
  nyco.inputAutocomplete({
    options: [
      ['Bronx'], ['Queens']
    ]
  });
</script>

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.inputAutocomplete({
  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 accessiblity 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 InputAutocomplete class accepts an object {} with two properties: selector and options.

Option Type Importance Description
options array required The suggested terms to be displayed in the dropdown. Each item is an array with the first item being the visible value. The following values within each array are treated as synonyms that score the priority of term higher if the user types it.
selected function optional A callback method that will be executed when a user has selected an option.
selector string optional The selector for the input element. If no selector is provided the default value will be set to [data-js="input-autocomplete__input"].

Cherry-picked Module Import

The ES6 module requires importing and object instantiation in your main script. The methods and configurations described above will work with the dedicated module.

// ES6
import InputAutocomplete from 'src/elements/inputs/input-autocomplete';

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

[//]: <> (#### Accessibility: Accessibility is suppported 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.)