# Datalist polyfill (auto-complete)

Questions or comments?

## Purpose

The HTML5 `input list` attribute and the `datalist` element add auto-complete functionality to specific text input fields by dynamically displaying a list of words that match the user’s input. Because some browsers do not support this functionality natively, this polyfill emulates the same functionality using generic HTML and WAI-ARIA. Browsers that do not support the `input list` attribute and the `datalist` element natively ignore the auto-complete functionality and therefore, the text input field behaves like it normally does. Implements the WAI-ARIA Combo Box design pattern.

## Use when

- Adding auto-complete functionality to specific text input fields

## Working example

    <label for="city">City</label>
    <input type="text" id="city" name="city" list="suggestions" />
    <datalist id="suggestions">
    	<!--[if lte IE 9]><select><![endif]-->
    	<option label="" value="Calgary"></option>
    	<option label="" value="Edmonton"></option>
    	<option label="" value="Iqualuit"></option>
    	<option label="" value="Ottawa"></option>
    	<option label="" value="Montreal"></option>
    	<option label="" value="St. John"></option>
    	<option label="" value="St. John's"></option>
    	<option label="" value="Toronto"></option>
    	<option label="" value="Vancouver"></option>
    	<option label="" value="Whitehorse"></option>
    	<option label="" value="Winnipeg"></option>
    	<option label="" value="Yellowknife"></option>
    	<!--[if lte IE 9]></select><![endif]-->
    </datalist>

- English example
- French example

## How to implement

To use the polyfill, the standard `input list` attribute and `datalist` element must be used. In cases where a browser doesn't support this attribute and element, the polyfill is automatically loaded.

## Configuration options

Configuration options available for the `datalist` element (HTML5 specification)

## Events

Event | Trigger | What it does
--- | --- | ---
`wb-init.wb-datalist` | Triggered manually (e.g., `$( "input[type=list]" ).trigger( "wb-init.wb-datalist" );`). | Used to manually initialize the `datalist` polyfill on an `input` element with a `list` attribute. Note: The `datalist` polyfill will be initialized automatically unless the `input list` attribute and `datalist` element are added after the page has already loaded.
`wb-ready.wb-datalist` (v4.0.5+) | Triggered automatically after the `datalist` polyfill initializes. Note: This event will only be triggered if the polyfill is loaded. The polyfill will not load for browsers with native `datalist` support. | Used to identify where the `datalist` polyfill initialized (target of the event)
    $( document ).on( "wb-ready.wb-datalist", "input[type=list]", function( event ) {
    });
    $( "input[type=list]" ).on( "wb-ready.wb-datalist", function( event ) {
    });
`wb-ready.wb` (v4.0.5+) | Triggered automatically when WET has finished loading and executing. | Used to identify when all WET plugins and polyfills have finished loading and executing.
    $( document ).on( "wb-ready.wb", function( event ) {
    });

## Source code

Datalist polyfill source code on GitHub

Date modified:
  2014-08-06