HTMLLabelElement.form — Eigenschaft · JavaScript-Referenz

Signatur

get HTMLLabelElement.form

Beschreibung

Die schreibgeschützte Eigenschaft form eines <label>-Elements liefert das Formular, zu dem das verknüpfte Steuerelement gehört. Maßgeblich ist also nicht, wo das Label selbst steht, sondern das Steuerelement aus label.control. Im Kern entspricht die Eigenschaft dem Ausdruck label.control?.form ?? null.

Ein Label wird entweder über das Attribut for (die ID des Steuerelements) oder durch Verschachtelung mit einem Steuerelement verknüpft. Gehört dieses Steuerelement zu einem Formular, kommt das zugehörige HTMLFormElement zurück. Das gilt auch, wenn das Steuerelement mit dem Attribut form="…" außerhalb des <form>-Elements steht.

Die Eigenschaft gibt null zurück, wenn:

das Label mit keinem Steuerelement verknüpft ist,
das Steuerelement zu keinem Formular gehört oder
das Steuerelement zwar ein Label haben kann, aber nicht zu einem Formular gehören kann, etwa <meter> oder <progress>.

Praktisch ist die Eigenschaft bei Klick-Handlern, in der Validierung oder bei eigenen Komponenten, die von einem Label aus das passende Formular finden müssen, ohne den DOM-Baum selbst zu durchsuchen.

Rückgabewert

Typ

HTMLFormElement | null

Beschreibung

Das Formular, zu dem das verknüpfte Steuerelement gehört, oder null, wenn es kein verknüpftes Steuerelement oder kein zugehöriges Formular gibt.

Beispiele

Formular über ein for-Label ermitteln

// HTML:
// <form id="login">
//   <label for="user">Benutzer</label>
//   <input id="user" name="user">
// </form>

const label = document.querySelector('label[for="user"]');
console.log(label.form?.id);
console.log(label.form === label.control.form);

login true

Label außerhalb des Formulars, Steuerelement mit form-Attribut

// HTML:
// <form id="newsletter"></form>
// <label>E-Mail
//   <input type="email" name="mail" form="newsletter">
// </label>

const label = document.querySelector('label');
// Das Label steht nicht im <form>, aber das Input gehört per form-Attribut dazu
console.log(label.closest('form'));
console.log(label.form.id);

null newsletter

Fälle, in denen null zurückkommt

// HTML:
// <label id="a">Ohne Steuerelement</label>
// <label id="b">Fortschritt <progress value="30" max="100"></progress></label>
// <label id="c">Frei <input name="frei"></label>

for (const id of ['a', 'b', 'c']) {
  const label = document.getElementById(id);
  console.log(id, label.control?.localName ?? '-', label.form);
}

a - null b progress null c input null

Beim Klick auf ein Label das ganze Formular prüfen

document.addEventListener('click', (event) => {
  const label = event.target.closest('label');
  if (!label) return;

  const form = label.form;
  if (form && !form.checkValidity()) {
    console.log(`Formular "${form.name || form.id}" ist noch unvollständig.`);
  }
});

// Wichtig · Fallstricke

Schreibgeschützt: Wenn man label.form einen Wert zuweist, passiert nichts, im Strict Mode gibt es einen TypeError. Um ein Steuerelement einem Formular zuzuordnen, setzt man das Attribut form am Steuerelement, nicht am Label.
Nicht mit closest('form') verwechseln: Die Eigenschaft richtet sich nach dem Formular des verknüpften Steuerelements, nicht nach dem Elternelement des Labels. Ältere Browser hatten dieses Verhalten anders umgesetzt. Die aktuelle Spezifikation und alle modernen Browser verwenden das Formular des Steuerelements.
Ändert sich die Verknüpfung (z. B. über label.htmlFor = … oder ein geändertes form-Attribut am Steuerelement), wird der Wert bei jedem Zugriff neu berechnet. Er wird nicht zwischengespeichert.
Zeigt for auf eine ID, die es nicht gibt, oder auf ein Element, das kein Label haben kann (z. B. ein <div>), sind control und form beide null.
Die Eigenschaft wird von allen aktuellen Browsern unterstützt.

Siehe auch

HTMLLabelElement.control HTMLLabelElement.htmlFor HTMLLabelElement HTMLFormElement HTMLInputElement.form HTMLInputElement.labels HTMLAreaElement.port