HTMLFormElement.submit() — Methode · JavaScript-Referenz

Signatur

HTMLFormElement.prototype.submit()

Beschreibung

Die Methode HTMLFormElement.submit() sendet ein <form>-Element per Skript ab. Der Browser baut aus den Formularfeldern die Anfrage auf, nutzt dafür die Attribute action, method, enctype und target und navigiert anschließend zur Antwortseite. Ohne abweichendes target wird also die aktuelle Seite ersetzt.

Wichtig ist, was submit() überspringt: Es wird kein submit-Event ausgelöst, die eingebaute Constraint-Validierung (required, pattern, min/max …) läuft nicht, und ein Submitter-Button wird weder übertragen noch berücksichtigt. submit() schickt die Daten also ohne jede Prüfung ab.

Soll sich das Formular so verhalten, als hätte der Nutzer auf einen Absende-Button geklickt, ist requestSubmit() die bessere Wahl. Diese Methode prüft die Felder, löst das submit-Event aus (das sich per preventDefault() abbrechen lässt) und kann einen bestimmten Submitter-Button mitschicken. submit() passt vor allem, wenn du Daten gezielt ohne Event-Handler absenden willst, etwa nach eigener Prüfung in einem submit-Handler oder bei versteckten Formularen für Weiterleitungen, z. B. zu Zahlungsanbietern.

Rückgabewert

Typ

void

Beschreibung

Gibt undefined zurück. Die Navigation bzw. Übertragung läuft asynchron durch den Browser.

Beispiele

Formular nach eigener asynchroner Prüfung absenden

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

form.addEventListener('submit', async (event) => {
  event.preventDefault();
  const email = form.elements.email.value;

  const res = await fetch(`/api/email-frei?email=${encodeURIComponent(email)}`);
  const { frei } = await res.json();

  if (frei) {
    // submit() löst KEIN erneutes submit-Event aus -> keine Endlosschleife
    form.submit();
  } else {
    form.elements.email.setCustomValidity('E-Mail ist bereits vergeben');
    form.reportValidity();
  }
});

Verstecktes POST-Formular für eine Weiterleitung erzeugen

const postRedirect = (url, daten) => {
  const form = document.createElement('form');
  form.method = 'POST';
  form.action = url;
  form.hidden = true;

  for (const [name, value] of Object.entries(daten)) {
    const input = document.createElement('input');
    input.type = 'hidden';
    input.name = name;
    input.value = value;
    form.append(input);
  }

  document.body.append(form); // Formular muss im Dokument hängen
  form.submit();
};

postRedirect('https://zahlung.example.com/checkout', { bestellung: '4711', betrag: '19.99' });

Unterschied zwischen submit() und requestSubmit()

const form = document.querySelector('form');
form.addEventListener('submit', () => console.log('submit-Event ausgelöst'));

// Keine Validierung, kein Event:
// form.submit();

// Mit Validierung und Event (empfohlen für 'Nutzer-ähnliches' Absenden):
form.requestSubmit();

submit-Event ausgelöst

// Wichtig · Fallstricke

Kein submit-Event, keine Validierung: Handler, die mit preventDefault() Daten per fetch senden wollen, werden umgangen. Nutze requestSubmit(), wenn Validierung und Event gewünscht sind.
Namenskonflikt: Hat ein Feld name=\"submit\" oder id=\"submit\", überdeckt es die Methode. form.submit zeigt dann auf das Element, und der Aufruf wirft einen TypeError: form.submit is not a function. Abhilfe: Feld umbenennen oder HTMLFormElement.prototype.submit.call(form) verwenden.
Das Formular sollte im Dokument eingehängt sein. Ohne Verbindung zum Dokument wird die Übertragung abgebrochen.
Die Sandbox-Regel allow-forms in <iframe sandbox> und die CSP-Direktive form-action können das Absenden blockieren.
Bei target=\"_blank\" kann ein Popup-Blocker eingreifen, wenn der Aufruf nicht direkt aus einer Nutzeraktion kommt.
Die Methode wird in allen Browsern unterstützt. requestSubmit() gibt es erst seit etwa 2019/2021 (Safari 16).

Siehe auch

HTMLFormElement.requestSubmit() HTMLFormElement.reset() HTMLFormElement.reportValidity() HTMLFormElement new UIEvent()