Signatur
Beschreibung
Die schreibgeschützte Eigenschaft list eines HTMLInputElement gibt das <datalist>-Element zurück, dessen id im list-Attribut des Eingabefelds steht. Über diese Verknüpfung zeigt der Browser beim Tippen Vorschläge an (Autovervollständigung), ohne dass der Nutzer auf diese Werte festgelegt wird.
Der Rückgabewert ist null, wenn kein list-Attribut gesetzt ist, wenn die angegebene id im Dokument nicht existiert, wenn das referenzierte Element kein <datalist> ist oder wenn der Eingabetyp keine Vorschlagslisten unterstützt (z. B. hidden, checkbox, radio, file, password, Schaltflächen).
Die Eigenschaft eignet sich, um per Skript auf die Vorschläge zuzugreifen – etwa um sie auszulesen, zu filtern oder dynamisch neue <option>-Elemente hinzuzufügen. Um die Verknüpfung selbst zu ändern, muss das Attribut per setAttribute('list', id) gesetzt werden, da die Eigenschaft nur lesbar ist.
Rückgabewert
<datalist>-Element oder null, wenn keine gültige Verknüpfung besteht.Beispiele
Vorschläge einer Datalist auslesen
// HTML:
// <input id="browser" list="browsers">
// <datalist id="browsers">
// <option value="Firefox"></option>
// <option value="Chrome"></option>
// <option value="Safari"></option>
// </datalist>
const input = document.querySelector('#browser');
const datalist = input.list;
if (datalist) {
const werte = [...datalist.options].map((opt) => opt.value);
console.log(werte);
}Vorschläge dynamisch aus einer API nachladen
// HTML: <input id="stadt" list="staedte"> <datalist id="staedte"></datalist>
const input = document.querySelector('#stadt');
input.addEventListener('input', async () => {
const liste = input.list;
if (!liste || input.value.length < 2) return;
const res = await fetch(`/api/staedte?q=${encodeURIComponent(input.value)}`);
const staedte = await res.json(); // z. B. ["Berlin", "Bern"]
liste.replaceChildren(
...staedte.map((name) => new Option(name))
);
});Verknüpfung per Attribut setzen und prüfen
const input = document.createElement('input');
const dl = document.createElement('datalist');
dl.id = 'farben';
dl.append(new Option('Rot'), new Option('Grün'));
document.body.append(input, dl);
console.log(input.list); // noch keine Verknüpfung
// input.list = dl; // wirkungslos – Eigenschaft ist schreibgeschützt
input.setAttribute('list', 'farben');
console.log(input.list === dl);
input.type = 'checkbox';
console.log(input.list); // Typ unterstützt keine Liste// Wichtig · Fallstricke
- Schreibgeschützt: Eine Zuweisung an
input.listwird ignoriert (im Strict Mode wirft sie einenTypeError). Die Verknüpfung ändert man übersetAttribute('list', 'id'). - Die Eigenschaft gibt
nullzurück, wenn dieidauf ein anderes Element als<datalist>zeigt – vor dem Zugriff auf.optionsdaher immer aufnullprüfen. - Das Datalist-Element muss sich im selben Dokument bzw. derselben Shadow-Root wie das Eingabefeld befinden; über Shadow-DOM-Grenzen hinweg funktioniert die
id-Referenz nicht. - Kompatibilität: Die Eigenschaft wird von allen modernen Browsern unterstützt. Die Darstellung der Vorschläge ist aber je nach Browser unterschiedlich (z. B. eingeschränkt bei
type=\"color\"odertype=\"range\", auf manchen Mobilgeräten nur teilweise); das Aussehen lässt sich per CSS kaum anpassen.