---
{
	"title": "Datalist polyfill (auto-complete)",
	"language": "en",
	"category": "Polyfills",
	"categoryfile": "polyfills",
	"description": "Emulates input list attribute and datalist element support for browsers that do not have support. This adds auto-complete functionality to specific input fields by dynamically displaying a list of words that match the datalist.",
	"altLangPrefix": "datalist",
	"dateModified": "2023-06-19"
}
---
<span class="wb-prettify all-pre hide"></span>

<section>
	<h2>Purpose</h2>
	<p>The HTML5 <code>input list</code> attribute and the <code>datalist</code> 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 <code>input list</code> attribute and the <code>datalist</code> element natively ignore the auto-complete functionality and therefore, the text input field behaves like it normally does. Implements the <a href="https://www.w3.org/TR/wai-aria-practices/#combobox">WAI-ARIA Combo Box design pattern</a>.</p>
</section>

<section>
	<h2>Use when</h2>
	<ul>
		<li>Adding auto-complete functionality to specific text input fields</li>
	</ul>
</section>

<section>
	<h2>Working example</h2>

	<pre><code>&lt;label for="city"&gt;City&lt;/label&gt;
&lt;input type="text" id="city" name="city" list="suggestions" /&gt;
&lt;datalist id="suggestions"&gt;
	&lt;option label="" value="Calgary"&gt;&lt;/option&gt;
	&lt;option label="" value="Edmonton"&gt;&lt;/option&gt;
	&lt;option label="" value="Iqualuit"&gt;&lt;/option&gt;
	&lt;option label="" value="Ottawa"&gt;&lt;/option&gt;
	&lt;option label="" value="Montreal"&gt;&lt;/option&gt;
	&lt;option label="" value="St. John"&gt;&lt;/option&gt;
	&lt;option label="" value="St. John's"&gt;&lt;/option&gt;
	&lt;option label="" value="Toronto"&gt;&lt;/option&gt;
	&lt;option label="" value="Vancouver"&gt;&lt;/option&gt;
	&lt;option label="" value="Whitehorse"&gt;&lt;/option&gt;
	&lt;option label="" value="Winnipeg"&gt;&lt;/option&gt;
	&lt;option label="" value="Yellowknife"&gt;&lt;/option&gt;
&lt;/datalist&gt;</code></pre>

	<ul>
		<li><a href="../../../demos/datalist/datalist-en.html">English example</a></li>
		<li><a href="../../../demos/datalist/datalist-fr.html">French example</a></li>
	</ul>
</section>

<section>
	<h2>How to implement</h2>
	<p>To use the polyfill, the standard <code>input list</code> attribute and <code>datalist</code> element must be used. In cases where a browser doesn't support this attribute and element, the polyfill is automatically loaded.</p>
</section>

<section>
	<h2>Configuration options</h2>
	<p><a href="https://www.w3.org/TR/html5/forms.html#the-datalist-element">Configuration options available for the <code>datalist</code> element (HTML5 specification)</a></p>
</section>

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

<section>
	<h2>Source code</h2>
	<p><a href="https://github.com/wet-boew/wet-boew/tree/master/src/polyfills/datalist">Datalist polyfill source code on GitHub</a></p>
</section>
