Datalist polyfill (auto-complete)

Looking for WET v3.1?

As of September 23, 2014, version 3.1 of the Web Experience Toolkit is no longer supported. The source code and documentation have been moved to the wet-boew-legacy repository.

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 Auto Complete design pattern.

Use when

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>

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: