HTMLOptionsCollection.add() — Methode · JavaScript-Referenz

Signatur

HTMLOptionsCollection.prototype.add(item, before)

Beschreibung

Die Methode add() der HTMLOptionsCollection (erreichbar über select.options) fügt ein HTMLOptionElement oder ein HTMLOptGroupElement in die zugehörige Auswahlliste ein. Ohne zweiten Parameter landet das Element am Ende, mit before vor dem angegebenen Element bzw. vor dem Element am angegebenen Index.

Typische Anwendungsfälle sind dynamisch befüllte Dropdowns: abhängige Auswahlfelder (Land → Stadt), Optionen aus einer API-Antwort oder das nachträgliche Ergänzen einer vom Nutzer angelegten Kategorie. In Kombination mit dem Konstruktor new Option(text, value, defaultSelected, selected) ist das deutlich kompakter als document.createElement() plus appendChild().

Funktional entspricht select.options.add() der Methode HTMLSelectElement.prototype.add(). Das Element wird dabei wie bei insertBefore() verschoben, falls es sich bereits im DOM befindet – es wird also nicht kopiert.

Parameter

Name	Typ	Default	Beschreibung
$item Pflicht	HTMLOptionElement \| HTMLOptGroupElement		Das einzufügende Element. Meist per `new Option()` oder `document.createElement('optgroup')` erzeugt.
$before	HTMLElement \| number \| null	null	Element oder Index, vor dem eingefügt wird. Bei `null`, `undefined` oder einem Index außerhalb des Bereichs wird am Ende angefügt.

Rückgabewert

Typ

undefined

Beschreibung

Kein Rückgabewert; die Collection und das DOM werden direkt verändert.

Beispiele

Option am Ende anfügen

const select = document.querySelector('#farbe');

// new Option(text, value)
select.options.add(new Option('Grün', 'gruen'));

console.log(select.options.length);
console.log(select.options[select.options.length - 1].value);

3 gruen

Platzhalter an erster Stelle einfügen

const select = document.querySelector('#land');

const platzhalter = new Option('Bitte wählen …', '', true, true);
platzhalter.disabled = true;

// Index 0 = vor der ersten vorhandenen Option
select.options.add(platzhalter, 0);

console.log(select.options[0].text);

Bitte wählen …

Dropdown aus API-Daten mit optgroup befüllen

const ladeStaedte = async (select) => {
  const res = await fetch('/api/staedte');
  const daten = await res.json(); // { "Deutschland": ["Berlin", ...], ... }

  select.options.length = 0; // alte Einträge entfernen

  for (const [land, staedte] of Object.entries(daten)) {
    const gruppe = document.createElement('optgroup');
    gruppe.label = land;
    for (const stadt of staedte) {
      gruppe.append(new Option(stadt, stadt.toLowerCase()));
    }
    select.options.add(gruppe);
  }
};

ladeStaedte(document.querySelector('#stadt'));

Vor einer bestimmten Option einfügen

const select = document.querySelector('#groesse');
const optionL = [...select.options].find((o) => o.value === 'l');

select.options.add(new Option('M', 'm'), optionL);

console.log([...select.options].map((o) => o.value).join(', '));

s, m, l

// Wichtig · Fallstricke

Fehler: Ist item ein Vorfahre des <select>, wird ein HierarchyRequestError geworfen. Ist before ein Element, das nicht Nachfahre des <select> ist, entsteht ein NotFoundError.
Verschieben statt Kopieren: Ein bereits eingefügtes Option-Element wird beim erneuten add() umgehängt. Für Duplikate option.cloneNode(true) verwenden.
Performance: Bei sehr vielen Einträgen die Optionen zunächst in ein DocumentFragment oder eine <optgroup> sammeln und dann einmal einfügen, um wiederholte Layout-Berechnungen zu vermeiden.
Sicherheit: new Option(text) setzt Text sicher; Nutzerdaten nicht per innerHTML in Optionen schreiben (XSS-Gefahr).
Kompatibilität: In allen modernen Browsern unterstützt. Sehr alte IE-Versionen erwarteten beim zweiten Parameter nur einen Index.

Siehe auch

HTMLCollection.namedItem() HTMLOptionsCollection.remove() HTMLAllCollection.item() HTMLCollection.item() HTMLAllCollection.namedItem()