The <datalist> Element

Basic

The <datalist> element supplies a set of predefined suggestions for another form control. It is not itself an input, it does not force the user to choose one of its suggestions, and it is not a replacement for <select>. Its job is to enrich an associated control with browser-provided suggestions while leaving the control’s own value model and validation rules in charge.

What <datalist> represents

A datalist represents a collection of predefined options for another control. The usual pattern is an <input> with a list attribute whose value is the id of the datalist. The browser can then offer suggestions while the input remains capable of accepting a value that is not present in the list.

<label for="browser">Browser</label>
<input id="browser" name="browser" list="browsers">
<datalist id="browsers">
  <option value="Firefox">
  <option value="Safari">
  <option value="Chrome">
</datalist>

<input list="cities">
<? id="cities">
  <option value="Cairo">
</datalist>

Datalist is not the control

The datalist does not own the editable value, focus, form submission, or constraint-validation state of the associated input. Those responsibilities remain with the input or other supported control. This distinction is the foundation for understanding every advanced datalist behavior.

Datalist versus select

A <select> constrains the user to selecting from its option set, subject to its selection model. A datalist supplies suggestions to a separate control. An input connected to a datalist can still contain a value that is not one of the suggestions.

<label for="city">City</label>
<input id="city" name="city" list="cities">
<datalist id="cities">
  <option value="Cairo">
  <option value="Alexandria">
</datalist>

The association: list points to id

The normal association is one-way: the form control has a list attribute whose value is the id of the datalist in the same tree. The datalist itself does not receive a special “for” attribute.

<input id="language" list="languages">
<datalist id="languages">
  <option value="Python">
  <option value="Rust">
</datalist>

The id must be unique within the relevant document tree. If the referenced id does not identify a datalist in the same tree, the control does not obtain that datalist as its list.

<input id="city" list="?">
<datalist id="cities">
  <option value="Cairo">
  <option value="Alexandria">
</datalist>

Global attributes only

The datalist element has no datalist-specific content attributes. It accepts global attributes. The important configuration happens through the association from the supported control and through the option descendants.

The element is hidden from ordinary rendering

The datalist itself represents nothing in the normal rendered page. Its option descendants provide data for the associated control’s user-agent interface. Authors should therefore not design a page layout that depends on datalist being visibly rendered as a list.

<datalist id="colors">
  <option value="#ff0000">
  <option value="#00ff00">
</datalist>

Basic syntax

<label for="fruit">Fruit</label>
<input id="fruit" name="fruit" list="fruit-options">
<datalist id="fruit-options">
  <option value="Apple">
  <option value="Banana">
  <option value="Mango">
</datalist>

Give the actual control an accessible label, give the datalist a unique id, and make the control’s list value match that id exactly.

What the user is allowed to enter

The associated control remains authoritative. For a text-like input, the user can normally type arbitrary text even when suggestions are present. Choosing a suggestion fills the control with that option value; it does not turn the input into a closed list.

Suggestion is not validation

A suggestion appearing in a datalist does not mean the submitted value is valid. If the application requires membership in a finite set, enforce that requirement explicitly with an appropriate control or validation rule and verify the submitted value on the server.

Begin with the control

When authoring a datalist feature, start by asking which actual form control owns the value. Then decide whether suggestions improve that control. This prevents the common architectural mistake of treating datalist as a standalone widget.

Intermediate

Which controls can use list?

The HTML input model defines list support for particular input states rather than for every possible control. Current HTML supports list suggestions for applicable input states such as text, search, url, tel, email, number, date/time states, range, and color, with the exact behavior determined by the input state and user agent.

Text-like suggestions

For text, search, url, tel, and email controls, datalist commonly appears as an autosuggestion surface. The browser may display the option value and, depending on browser behavior, supplementary label information.

<label for="framework">Framework</label>
<input id="framework" list="frameworks" name="framework">
<datalist id="frameworks">
  <option value="Django" label="Python web framework">
  <option value="Rails" label="Ruby web framework">
  <option value="Laravel" label="PHP web framework">
</datalist>

The option value remains the important data

For a datalist suggestion, the option value is what gets inserted into the associated control when that suggestion is chosen. The browser may expose label or text in its suggestion UI, but authors should not treat presentation text as a second submitted field.

The label attribute is supplemental

An option used by a datalist can have a label. User agents differ in how they present that label: it may be shown instead of the value, alongside it, or not visibly at all. Do not build application logic around a particular browser’s popup presentation.

Number suggestions

A number input can use datalist suggestions. The suggestions do not replace the number input’s own parsing and range rules. A value that is not one of the suggestions may still be accepted if it satisfies the number control’s rules.

<label for="quantity">Quantity</label>
<input id="quantity" name="quantity" type="number" list="quantities" min="1" max="100">
<datalist id="quantities">
  <option value="10">
  <option value="25">
  <option value="50">
</datalist>

Date and time suggestions

Date, month, week, time, and datetime-local controls can use predefined values where list support applies. The control still owns parsing, normalization, and validity for its particular state.

<label for="meeting">Preferred time</label>
<input id="meeting" name="meeting" type="time" list="meeting-times">
<datalist id="meeting-times">
  <option value="09:00">
  <option value="13:00">
  <option value="16:00">
</datalist>

Range tick marks

With a range input, datalist can provide predefined numeric positions that user agents may render as tick marks. This is a particularly useful example of datalist being a source of suggestions rather than a list of selectable submitted options.

<label for="tip">Tip</label>
<input id="tip" type="range" min="0" max="100" list="tip-marks">
<datalist id="tip-marks">
  <option value="0" label="0%">
  <option value="20" label="20%">
  <option value="50" label="50%">
  <option value="100" label="100%">
</datalist>

Color suggestions

A color input can use a datalist of color values. The browser may expose those values through its native color picker. The color control still owns the actual color value and its validation/normalization behavior.

<label for="brand-color">Brand color</label>
<input id="brand-color" type="color" list="brand-colors">
<datalist id="brand-colors">
  <option value="#0f766e">
  <option value="#2563eb">
  <option value="#7c3aed">
</datalist>

The same option element has different context

The <option> element is context-sensitive. Inside a select it participates in a selection model. Inside a datalist it provides a suggestion. Do not copy assumptions about select selectedness, placeholder options, or form submission directly into datalist code.

Option disabledness is not a datalist constraint system

An option’s disabled state and the way a user agent exposes it in a datalist suggestion UI should not be treated as a substitute for validation. If an application needs a value to be forbidden, validate the actual control value.

Datalist and forms

The datalist itself is not a form-associated control and does not contribute a name/value pair to form submission. The associated input or other control does.

<form action="/search" method="get">
  <label for="q">Search</label>
  <input id="q" name="q" list="popular-searches">
  <datalist id="popular-searches">
    <option value="html">
    <option value="css">
    <option value="javascript">
  </datalist>
  <button type="submit">Search</button>
</form>

The datalist does not need a name

Because the datalist is not itself submitted as a form control, giving it a name does not create a form-data field. The input’s name is what matters for ordinary form submission.

Datalist and autocomplete are different

Autocomplete can use browser-managed history and autofill mechanisms, while datalist is author-provided predefined suggestion data. They can coexist, and they solve related but distinct problems.

The input list IDL property

For a supported input, HTMLInputElement.list exposes the associated HTMLDataListElement or null. It is read-only as an IDL property; change the association by changing the input’s list attribute.

const input = document.querySelector("#framework");
console.log(input.list);

The datalist options collection

HTMLDataListElement exposes a read-only options HTMLCollection containing the option elements associated with that datalist. The collection is live, so DOM changes to the option descendants can affect what the collection contains.

const datalist = document.querySelector("#frameworks");
console.log(datalist.options.length);
console.log(datalist.options[0].value);

Dynamic suggestions

Applications can add, remove, or update option elements as data changes. This is useful when suggestions depend on the current application state, but dynamic generation should remain a presentation enhancement over a sound underlying input and validation model.

const list = document.querySelector("#frameworks");
const option = document.createElement("option");
option.value = "Phoenix";
list.append(option);

Do not confuse datalist with autocomplete search

A datalist is not a remote-search protocol. It does not define debouncing, fetching, ranking, filtering, pagination, authentication, or server-side search. If suggestions come from an API, JavaScript may update the datalist, but the application owns that data-fetching architecture.

Advanced

The two permitted content models

The current HTML content model permits either phrasing content, or zero or more option and script-supporting elements. This dual model exists so authors can provide an option-based datalist and so the element can participate in the more elaborate fallback pattern defined by the standard.

The fallback pattern

The standard describes an elaborate datalist form in which a select is placed inside the datalist, with labeling around it, so older or down-level clients can expose an alternative control. Modern authors should understand this as a standards-defined compatibility pattern rather than assuming datalist must always contain only direct option children.

<label>
  Animal:
  <input name="animal" list="animals">
</label>
<datalist id="animals">
  <label>
    or select from the list:
    <select name="animal">
      <option value="">
      <option>Cat
      <option>Dog
    </select>
  </label>
</datalist>

Why datalist can be tricky for accessibility

The HTML Standard leaves the user-agent presentation of suggestions to the implementation. Authors should therefore treat the suggestion interface as user-agent behavior rather than depending on a particular popup appearance, while keeping the underlying control usable without the suggestion presentation.

Browser UI is user-agent owned

The browser owns the popup presentation. Authors have very limited control over its typography, dimensions, high-contrast behavior, zoom behavior, keyboard interaction, and exact visual arrangement.

Do not style the popup by guessing selectors

There is no portable CSS contract for the internal suggestion popup. CSS that appears to work in one browser should not be treated as a standards-based datalist styling API.

Accessibility does not mean recreating the popup yourself

Replacing datalist with a custom ARIA combobox can provide control over presentation, but it also transfers responsibility for keyboard interaction, focus management, filtering, announcement, selection semantics, and synchronization to your application. Use native datalist when its behavior meets the product requirement; build a custom widget only when you have a concrete requirement the native control cannot satisfy.

The control still needs a real label

Datalist suggestions do not provide the accessible name for the associated input. Label the actual input with a <label> or another appropriate naming mechanism.

<label for="country">Country</label>
<input id="country" name="country" list="countries">
<datalist id="countries">
  <option value="Egypt">
  <option value="France">
</datalist>

Localization of suggestions

Suggestion values may be localized display strings or stable application tokens depending on what the control represents. Decide deliberately. If the user is entering a human-language value, localized suggestions can be appropriate. If the value is an application identifier, keep the machine-facing contract stable and expose human-readable context through labels or surrounding UI.

RTL and bidirectional text

The datalist popup is user-agent rendered, but the associated control and option data still participate in document direction and text-direction rules. Test Arabic, Hebrew, mixed-script values, URLs, email addresses, and numeric data rather than assuming a left-to-right suggestion UI will behave identically.

Security boundary: suggestions are untrusted input

Selecting a datalist suggestion does not make its value trustworthy. The user can usually type a different value, and even a suggestion supplied by the server is still client-controlled. Validate, authorize, normalize, and encode data at the appropriate server boundary.

Datalist does not prevent arbitrary input

This is the most important security and correctness distinction: a datalist is not an allowlist. If an application requires an identifier from a known set, the server must check membership or the UI must use a control/validation architecture that expresses that requirement.

Datalist and constraint validation

Constraint validation belongs to the associated form control. For example, a required input can still be invalid when empty even if a datalist exists, and a pattern or type constraint evaluates the control’s value rather than the datalist’s option set.

Datalist does not submit suggestions

The browser submits the actual value of the associated successful form control. The datalist itself contributes no independent form-data entry.

DOM mutation versus user choice

Changing the option elements changes the available suggestion data. It does not magically change an already-entered input value. Conversely, changing the input value does not mutate the datalist options. Keep these state machines conceptually separate.

Inspect the relationship in DevTools

When debugging, inspect three objects separately: the input element and its list attribute, the datalist element and its options collection, and the live input value. This makes broken IDs and mistaken assumptions much easier to identify.

const input = document.querySelector("#city");
console.log({ listId: input.getAttribute("list"), list: input.list, value: input.value });
console.log([...input.list?.options ?? []].map(option => option.value));

Broken association diagnosis

If suggestions do not appear, verify the control supports list, the list attribute contains the intended id, the datalist exists in the same tree, the id is unique, and the option values are valid for the intended control state. Then test in another current browser because the popup itself is user-agent UI.

Browser compatibility is part of product design

The HTML Standard defines fallback content for user agents that do not support the datalist feature. When suggestions are merely an aid, the underlying control remains the primary interface; when the suggestions are important, authors can provide the fallback form content described by the HTML Standard.

Graceful degradation

The strongest datalist pattern is progressive enhancement: make the input useful and correctly labeled without suggestions, then add datalist as a native enhancement. Never make the application unusable solely because the suggestion popup is unavailable.

When to use select instead

Use select when the user is choosing from a defined set and the control should express that constrained choice. Use datalist when the user is entering a value and predefined suggestions are helpful but should not necessarily restrict what can be entered.

When to use a custom combobox

Consider a custom combobox only when requirements such as remote querying, rich result rendering, advanced filtering, custom interaction, or application-specific behaviors genuinely exceed the native datalist model. If you take that path, you inherit the accessibility and interaction engineering that the browser normally provides.

Architecture for remote suggestions

For remote data, treat the datalist as a rendering target for a suggestion dataset, not as the data layer. Keep fetching, cancellation, debouncing, caching, authorization, and error handling outside the HTML element, then synchronize only the current suggestions into option elements.

Avoid stale suggestion races

If suggestions are fetched asynchronously, an older response can arrive after a newer query. Associate each response with the query that produced it and discard stale results before mutating the datalist.

Do not use suggestion text as an authorization decision

A suggestion can be helpful for choosing a valid record, but the server must still authorize the actual identifier submitted by the client. The presence of a value in a datalist is never evidence that the current user may access that record.

Practical implementation checklist

• Start with a real form control and a real accessible name.

• Give the datalist a unique id.

• Point the control’s list attribute at that id.

• Use option values that match the control’s expected data format.

• Treat labels as supplemental presentation, not a second submission channel.

• Do not assume suggestions restrict input.

• Validate actual submitted values on the server.

• Test keyboard, zoom, high-contrast, screen-reader, and RTL scenarios.

• Test current browsers because popup behavior is user-agent controlled.

• Provide a useful experience when datalist suggestions are unavailable.

Guru practice: design a resilient suggestion system

Build a city search field that uses a datalist for a small set of immediately useful suggestions. Then add asynchronous suggestions from an API. Keep the input independently usable, discard stale responses, preserve arbitrary user-entered values, and validate the final value on the server. Document which behavior comes from HTML and which behavior comes from your application.

What belongs in the future <option> lesson

The dedicated <option> lesson owns option semantics: value fallback, label/value distinctions, selectedness, disabledness, the Option constructor, and context-specific option behavior. This datalist lesson only explains those pieces enough to understand datalist’s contract.

What belongs in the future form-validation lesson

The future cross-element validation lesson will cover the complete constraint-validation model. Here we only establish that datalist suggestions do not themselves create an allowlist or validation rule.

What belongs in the future form-submission lesson

The future form-submission lesson will cover successful controls, entry lists, encoding, and submission algorithms in depth. Here the key fact is simply that the associated control—not the datalist—owns submitted data.

Final mental model

Think of <datalist> as a native suggestion source attached to another control. The control owns the value. The datalist owns predefined suggestions. The option elements carry suggestion data. The browser owns the popup. Your application owns validation, authorization, remote data, and graceful degradation.

Final author checklist

• Is the associated control correctly labeled?

• Does the control support list in the state you chose?

• Does list point to a unique datalist id in the same tree?

• Are suggestion values correctly formatted for the control?

• Have you avoided treating suggestions as an allowlist?

• Have you tested arbitrary user input?

• Have you tested accessibility and zoom behavior?

• Have you tested RTL and localized values where relevant?

• Have you considered browsers with limited datalist support?

• Does the feature remain useful without the popup?

The DOM interface

HTMLDataListElement exposes the options property as a read-only HTMLCollection. The element otherwise inherits ordinary HTMLElement behavior. It does not expose a value, selectedIndex, validity state, or form owner because it is not the form control holding the user’s value.

const list = document.querySelector("datalist");
console.log(list instanceof HTMLDataListElement);
console.log(list.options);

A datalist can be reused conceptually, but association is explicit

A control references a datalist by id. If several controls reference the same datalist, they share the same suggestion source. Whether that is a good design depends on whether the suggestion values make semantic sense for every control using them.

Do not overfit to one browser popup

Two browsers can expose the same underlying HTML datalist semantics through noticeably different UI. A standards-compliant application should rely on the value and association contract, not on pixel-level popup appearance.

Advanced review question

If a user types a value that is absent from the datalist, ask: “Does the control itself permit this value?” That question, rather than “Was it in the list?”, determines the correct validation architecture.