The HTML list attribute
Set an input's list attribute to a <datalist> id, and the browser suggests that datalist's options. With <input list="cities">, people can pick a listed city or type one that isn't there. Under the HTML standard, password, checkbox, radio, file, hidden and button inputs can't use it.
Overview
The HTML list attribute connects an <input> to a <datalist> of suggested values. Its value is the datalist's id. The browser uses the first element in the document with that id, and if that element isn't a datalist, the input gets no suggestions.
How the suggestions appear depends on the input type. Typically, text, search, url, tel, email and number fields list them in a drop-down, and a range slider shows them as tick marks. Color, date and time pickers can show the values too.
The values are suggestions, not requirements. A value that isn't in the datalist passes validation as long as it meets the input's other rules, so the form submits it like any other value.
Support for suggestions differs by input type and platform. Firefox shows none on date and time inputs, offers color suggestions only on Windows and Linux, and doesn't show the drop-down at all on Android.
Syntax
<label for="city">City</label>
<input id="city" name="city" list="cities">
<datalist id="cities">
<option value="Lisbon"></option>
<option value="London"></option>
<option value="Lyon"></option>
</datalist>Values
| Value |
|---|
The id of a <datalist> element. |
Example
<form id="trip">
<label for="city">City</label>
<input id="city" name="city" list="cities">
<datalist id="cities">
<option value="Lisbon"></option>
<option value="London"></option>
<option value="Lyon"></option>
<option value="Lima"></option>
</datalist>
<p style="margin:10px 0">
<label for="tip">Tip</label>
<input type="range" id="tip" name="tip" min="0" max="20" step="5" value="10" list="tips">
</p>
<datalist id="tips">
<option value="0"></option>
<option value="5"></option>
<option value="10"></option>
<option value="15"></option>
<option value="20"></option>
</datalist>
<button>Check</button>
<p id="msg" role="status" style="overflow-wrap:anywhere"></p>
</form>
<p>Type L in City and pick a suggestion, or type Paris, then press Check.</p>
<script>
const form = document.getElementById('trip');
const city = document.getElementById('city');
const msg = document.getElementById('msg');
form.addEventListener('submit', function (e) {
e.preventDefault();
const listed = [...city.list.options].some(o => o.value === city.value);
msg.textContent = (city.value || 'An empty city') +
(listed ? ' is in the list.' : ' is not in the list, and the form accepts it anyway.') +
' Tip ' + form.elements.tip.value + '%.';
});
</script>More Examples
Best practices
- Every option in a
listattribute's datalist should have avalue, the text that goes into the field. A label attribute or the option's text can then describe it. - Match option values to the input type's format, such as
#336699for a color or14:30for a time. Values the type can't take are left out of the suggestions. - Line up a range input's step with its ticks, such as
step="5"for ticks at 0, 5, 10, 15 and 20. The ticks suggest values, and step makes sure the value lands on one. - Share one datalist between inputs that need the same suggestions. Several inputs can name the same id in their list attribute.
Accessibility
Suggestions from the list attribute have known accessibility gaps. Don't count on their text growing with page zoom, or on page CSS restyling them for high-contrast mode. Some screen reader and browser pairs, including NVDA with Firefox, don't announce them.
Frequently asked questions
Should I use the list attribute or a select element?
Which input types support the list attribute?
Why is my datalist not showing suggestions for the list attribute?
How do I switch the list attribute to another datalist in script?
setAttribute('list', 'other-id'), since the list property is read-only. Reading input.list returns the linked datalist element, or null when there is none.
