HTMLFormElement.elements — Eigenschaft · JavaScript-Referenz

Signatur

get HTMLFormElement.elements

Beschreibung

Die schreibgeschützte Eigenschaft elements liefert alle aufgeführten Formularelemente (engl. listed elements), die dem <form> zugeordnet sind. Dazu gehören <button>, <fieldset>, <input> (außer type="image"), <object>, <output>, <select>, <textarea> sowie formularzugehörige Custom Elements (static formAssociated = true).

Die Collection ist live: Werden Steuerelemente hinzugefügt oder entfernt, spiegelt sie das sofort wider. Die Reihenfolge entspricht der Dokumentreihenfolge. Auch Elemente außerhalb des <form>-Tags gehören dazu, wenn sie per form="formular-id"-Attribut zugeordnet sind; umgekehrt fehlen verschachtelte Elemente, deren form-Attribut auf ein anderes Formular zeigt.

Der Zugriff funktioniert über den Index (form.elements[0]), über name bzw. id (form.elements.email oder form.elements.namedItem("email")). Teilen sich mehrere Elemente denselben Namen, etwa eine Radio-Gruppe, wird eine RadioNodeList zurückgegeben, deren value den Wert des ausgewählten Radiobuttons enthält.

Typische Einsatzgebiete sind eigene Validierung, das Sperren aller Felder während des Absendens, das Auslesen von Werten ohne querySelector und generische Formular-Serialisierung.

Rückgabewert

Typ

HTMLFormControlsCollection

Beschreibung

Eine live aktualisierte Collection aller dem Formular zugeordneten aufgeführten Steuerelemente. Unterstützt length, item(index), namedItem(name), Index- und Namenszugriff sowie Iteration mit for...of.

Beispiele

Felder per Name und Index auslesen

// <form id="login"><input name="user" value="anna"><input name="pass" type="password" value="geheim"><button>Login</button></form>
const form = document.getElementById('login');
const { user, pass } = form.elements;

console.log(form.elements.length);
console.log(user.value);
console.log(form.elements[1].type);
console.log(form.elements.namedItem('pass') === pass);

3 anna password true

Alle Felder während des Absendens sperren

const form = document.querySelector('#kontakt');

form.addEventListener('submit', async (event) => {
  event.preventDefault();
  const controls = [...form.elements];
  controls.forEach((el) => { el.disabled = true; });

  try {
    await fetch('/api/kontakt', { method: 'POST', body: new FormData(form) });
    console.log('Gesendet');
  } finally {
    controls.forEach((el) => { el.disabled = false; });
  }
});

Gesendet

Radio-Gruppe über RadioNodeList auswerten

// <form id="umfrage">
//   <input type="radio" name="farbe" value="rot">
//   <input type="radio" name="farbe" value="blau" checked>
// </form>
const form = document.getElementById('umfrage');
const gruppe = form.elements.farbe;

console.log(gruppe instanceof RadioNodeList);
console.log(gruppe.length);
console.log(gruppe.value);

gruppe.value = 'rot'; // wählt den passenden Radiobutton aus
console.log(gruppe[0].checked);

true 2 blau true

Zuordnung über das form-Attribut und Live-Verhalten

// <form id="bestellung"><input name="menge"></form>
// <input name="gutschein" form="bestellung">  (außerhalb des Formulars)
const form = document.getElementById('bestellung');
const controls = form.elements;
console.log([...controls].map((el) => el.name));

const notiz = document.createElement('textarea');
notiz.name = 'notiz';
form.append(notiz);
console.log(controls.length); // Collection hat sich automatisch aktualisiert

["menge", "gutschein"] 3

// Wichtig · Fallstricke

<input type="image"> fehlt aus historischen Gründen in elements. Solche Elemente erreicht man nur über querySelector. Auch <label>, <option> und <datalist> gehören nicht dazu.
Namenskonflikte: Heißt ein Feld length, item oder namedItem, liefert der Punktzugriff die Eigenschaft bzw. Methode der Collection statt des Feldes. In solchen Fällen immer elements.namedItem("length") verwenden. Umgekehrt verdecken Felder wie name="submit" oder name="action" beim direkten Zugriff form.submit die Formular-Methoden. form.elements.submit ist hier die eindeutige Alternative.
Live-Collection: Wer beim Iterieren Elemente entfernt, überspringt dabei Einträge. Deshalb vorher mit [...form.elements] oder Array.from() kopieren.
Die Collection ist kein Array. forEach, map usw. gibt es erst nach der Umwandlung, for...of funktioniert aber direkt.
Deaktivierte Felder (disabled) sind enthalten, werden von FormData aber nicht übertragen.
Kompatibilität: In allen Browsern verfügbar. Formularzugehörige Custom Elements erscheinen erst in modernen Browsern (Chrome 77+, Firefox 98+, Safari 16.4+).

Siehe auch

HTMLFormElement.length HTMLFormElement.name HTMLFormElement.relList HTMLFormElement.target HTMLFormElement.action