HTMLSelectElement.add() — Methode · JavaScript-Referenz

Signatur

HTMLSelectElement.prototype.add(element, before)

Beschreibung

Mit add() fügen Sie einem <select>-Element per Skript neue Einträge hinzu. Das ist besonders nützlich bei dynamischen Auswahllisten, etwa wenn Optionen nachträglich über fetch() geladen werden oder von einer anderen Auswahl abhängen (abhängige Dropdowns wie Land → Bundesland).

Das erste Argument ist ein HTMLOptionElement oder ein HTMLOptGroupElement. Ein HTMLOptionElement erzeugen Sie am bequemsten mit dem Konstruktor new Option(text, value, defaultSelected, selected). Ohne zweites Argument wird das Element am Ende der Liste angehängt.

Über das optionale zweite Argument before bestimmen Sie die Position: Entweder übergeben Sie ein bestehendes Element, vor dem eingefügt werden soll, oder einen Index (Zahl). Ist before gleich null, fehlt es oder liegt der Index außerhalb des Bereichs, wird das Element angehängt.

Die Methode verhält sich genauso wie HTMLOptionsCollection.add(), d. h. select.add(opt) und select.options.add(opt) sind gleichwertig.

Parameter

Name	Typ	Default	Beschreibung
$element Pflicht	HTMLOptionElement \| HTMLOptGroupElement		Das einzufügende `<option>`- oder `<optgroup>`-Element. Ein bereits im Dokument vorhandenes Element wird verschoben, nicht kopiert.
$before	HTMLElement \| number \| null	null	Element aus der Sammlung, vor dem eingefügt wird, oder dessen Index. Bei `null`, fehlendem Wert oder ungültigem Index wird am Ende angehängt.

Rückgabewert

Typ

undefined

Beschreibung

Die Methode gibt nichts zurück; das <select>-Element wird direkt verändert.

Beispiele

Option am Ende anhängen

const select = document.createElement('select');
select.add(new Option('Rot', 'red'));
select.add(new Option('Grün', 'green'));

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

2 green

An bestimmter Position einfügen (Index und Element)

const select = document.createElement('select');
select.add(new Option('B', 'b'));
select.add(new Option('C', 'c'));

// Per Index: vor Position 0 einfügen
select.add(new Option('A', 'a'), 0);

// Per Element: vor „C“ einfügen
const cOption = select.options[2];
select.add(new Option('B2', 'b2'), cOption);

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

a, b, b2, c

Optionen dynamisch per fetch laden

const citySelect = document.querySelector('#city');

const loadCities = async (countryCode) => {
  const res = await fetch(`/api/cities?country=${encodeURIComponent(countryCode)}`);
  const cities = await res.json(); // [{ id: 'ber', name: 'Berlin' }, ...]

  citySelect.length = 0; // vorhandene Optionen entfernen
  citySelect.add(new Option('Bitte wählen …', '', true, true));
  for (const { id, name } of cities) {
    citySelect.add(new Option(name, id));
  }
};

document.querySelector('#country')
  .addEventListener('change', (e) => loadCities(e.target.value));

Optionsgruppe hinzufügen

const select = document.createElement('select');
const group = document.createElement('optgroup');
group.label = 'Obst';
group.append(new Option('Apfel', 'apple'), new Option('Birne', 'pear'));

select.add(group);
console.log(select.options.length, select.options[0].parentElement.label);

2 Obst

// Wichtig · Fallstricke

Fehler: Ist element ein Vorfahre des <select> (bzw. before ein Element, das nicht zur Sammlung gehört), wird eine DOMException (HierarchyRequestError bzw. NotFoundError) geworfen.
Verschieben statt Kopieren: Ein bereits eingebundenes <option> wird an die neue Stelle verschoben. Für mehrere Listen jeweils neue Instanzen oder cloneNode() verwenden.
Altes Verhalten: Sehr alte Browser (IE ≤ 7) erwarteten beim zweiten Parameter nur einen Index; der ältere DOM-Level-2-Standard verlangte ein Element. Heute unterstützen alle Browser beide Varianten.
Sicherheit: new Option(text, …) setzt den Text als reinen Text – das ist XSS-sicher. Bauen Sie Optionen nicht per innerHTML aus Benutzer- oder API-Daten zusammen.
Leistung: Bei sehr vielen Optionen ist es effizienter, sie erst in ein DocumentFragment bzw. ein nicht eingehängtes <select> einzufügen oder select.append(...options) zu nutzen.
Das Hinzufügen löst kein change-Ereignis aus.

Siehe auch

new HTMLGeolocationElement() HTMLSelectElement.item() HTMLSelectElement.remove() HTMLSelectElement.namedItem() HTMLSelectElement.showPicker()