HTMLDataListElement — Schnittstelle · JavaScript-Referenz

Signatur

interface HTMLDataListElement extends HTMLElement

Beschreibung

Die Schnittstelle HTMLDataListElement steht für ein <datalist>-Element. Ein solches Element enthält eine Reihe von <option>-Elementen. Sie dienen als Vorschläge für ein <input>, das über sein Attribut list auf die id der Datalist verweist. Anders als bei <select> darf der Nutzer trotzdem beliebige eigene Werte eingeben. Die Vorschläge sind also nur eine Hilfe zur Autovervollständigung.

Zusätzlich zu allem, was von HTMLElement geerbt wird, bietet die Schnittstelle genau eine eigene Eigenschaft: options. Sie ist schreibgeschützt und liefert eine live HTMLCollection aller enthaltenen <option>-Elemente. Fügt man Optionen hinzu oder entfernt sie, ist die Sammlung sofort auf dem neuen Stand. Eigene Methoden gibt es nicht. Optionen legt man über die üblichen DOM-Methoden wie append(), replaceChildren() oder new Option() an.

Typische Einsatzfälle sind Suchfelder mit dynamischen Vorschlägen, etwa Städte, Produktnamen oder zuletzt verwendete Werte. Auch Eingabefelder vom Typ range, color, date oder time nutzen eine Datalist, zum Beispiel für Skalenmarkierungen oder voreingestellte Farben. Von einem <input> aus erreicht man die zugehörige Datalist direkt über die Eigenschaft input.list.

Parameter

Name	Typ	Default	Beschreibung
$options	HTMLCollection<HTMLOptionElement>		Schreibgeschützte Eigenschaft. Liefert eine live Sammlung aller `<option>`-Kindelemente der Datalist.

Beispiele

Datalist per JavaScript erzeugen und mit einem Input verknüpfen

const input = document.createElement('input');
input.setAttribute('list', 'staedte');
input.placeholder = 'Stadt wählen …';

const datalist = document.createElement('datalist');
datalist.id = 'staedte';

const staedte = ['Berlin', 'Hamburg', 'München', 'Köln'];
datalist.append(...staedte.map((name) => new Option(name)));

document.body.append(input, datalist);

console.log(datalist instanceof HTMLDataListElement);
console.log(datalist.options.length);
console.log(input.list === datalist);

true 4 true

Vorschläge dynamisch aus einer API nachladen

// HTML: <input id="suche" list="vorschlaege"><datalist id="vorschlaege"></datalist>
const suche = document.getElementById('suche');
const liste = suche.list; // HTMLDataListElement
let controller;

suche.addEventListener('input', async () => {
  const begriff = suche.value.trim();
  if (begriff.length < 2) return;

  controller?.abort();
  controller = new AbortController();

  try {
    const res = await fetch(`/api/produkte?q=${encodeURIComponent(begriff)}`, {
      signal: controller.signal,
    });
    const produkte = await res.json(); // z. B. ['Laptop', 'Lampe']
    liste.replaceChildren(...produkte.map((p) => new Option(p)));
    console.log(`${liste.options.length} Vorschläge geladen`);
  } catch (err) {
    if (err.name !== 'AbortError') console.error(err);
  }
});

2 Vorschläge geladen

Optionen auslesen und Eingabe validieren

// HTML: <input id="farbe" list="farben">
// <datalist id="farben"><option value="rot"><option value="grün"><option value="blau"></datalist>
const datalist = document.getElementById('farben');
const erlaubt = Array.from(datalist.options, (opt) => opt.value);
console.log(erlaubt);

const feld = document.getElementById('farbe');
feld.addEventListener('change', () => {
  const ok = erlaubt.includes(feld.value);
  feld.setCustomValidity(ok ? '' : 'Bitte eine Farbe aus der Liste wählen.');
  feld.reportValidity();
});

['rot', 'grün', 'blau']

Skalenmarkierungen für einen Schieberegler

const range = document.createElement('input');
range.type = 'range';
range.min = '0';
range.max = '100';
range.setAttribute('list', 'marken');

const marken = document.createElement('datalist');
marken.id = 'marken';
for (const wert of [0, 25, 50, 75, 100]) {
  marken.append(new Option('', String(wert)));
}

document.body.append(range, marken);
console.log([...marken.options].map((o) => o.value).join(', '));

0, 25, 50, 75, 100

// Wichtig · Fallstricke

Verknüpfung nur über das Attribut: input.list ist schreibgeschützt. Um ein Feld mit einer Datalist zu verbinden, schreibt man input.setAttribute('list', id). Die Zuweisung input.list = ... hat keine Wirkung.
Live-Sammlung: options ändert sich sofort mit dem DOM. Wer in einer Schleife Optionen entfernt, sollte vorher mit Array.from() eine Kopie anlegen, sonst werden Einträge übersprungen.
Keine Validierung: Eine Datalist schränkt die Eingabe nicht ein. Wenn nur bestimmte Werte erlaubt sein sollen, muss man selbst prüfen (z. B. mit setCustomValidity()) oder stattdessen <select> verwenden.
Darstellung: Das Vorschlags-Popup zeichnet der Browser selbst. Mit CSS lässt es sich praktisch nicht gestalten. Browser zeigen außerdem value und Beschriftung der Optionen unterschiedlich an und filtern auch unterschiedlich (Präfix- oder Teilstring-Suche).
Browser-Kompatibilität: Alle aktuellen Browser unterstützen die Schnittstelle. Bei bestimmten Eingabetypen gibt es Lücken: Firefox zeigt z. B. bei type="color" und teils bei Datums- und Zeitfeldern keine Vorschläge an. Skalenmarkierungen für range sind je nach Browser unterschiedlich gut sichtbar.
Barrierefreiheit: Screenreader geben Datalist-Vorschläge nicht zuverlässig aus. Für wichtige Auswahlen sollte man sich deshalb nicht allein auf die Datalist verlassen.

Siehe auch

HTMLDListElement HTMLDataElement HTMLDetailsElement HTMLOListElement HTMLUListElement