HTMLFormElement: submit — Ereignis · JavaScript-Referenz

Signatur

form.addEventListener("submit", handler)

Beschreibung

Das submit-Ereignis wird am Formular selbst ausgelöst, nicht am Button. Das passiert, wenn der Nutzer auf einen Absende-Button (<button type="submit"> oder <input type="submit">) klickt, in einem Eingabefeld Enter drückt oder wenn das Skript form.requestSubmit() aufruft. Das Ereignis-Objekt ist ein SubmitEvent. Dessen Eigenschaft submitter verrät, welcher Button das Absenden ausgelöst hat.

Meistens nutzt man das Ereignis, um das Formular clientseitig zu prüfen oder um die Daten per fetch() ohne Neuladen der Seite zu verschicken. Dazu ruft man event.preventDefault() auf. Das verhindert die normale Navigation, die der Browser sonst zur action-URL ausführt.

Man registriert den Handler entweder mit form.addEventListener("submit", handler) oder über die Eigenschaft form.onsubmit = handler. Das Ereignis steigt im DOM auf (Bubbling). Deshalb kann man auch mit Event-Delegation auf document alle Formulare zentral abfangen. Abbrechen lässt es sich ebenfalls (cancelable).

Wichtig: Beim Aufruf von form.submit() wird das Ereignis nicht ausgelöst, und die Formular-Validierung läuft nicht. Wer Handler und Validierung auslösen will, verwendet form.requestSubmit().

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"submit"`.
$handler Pflicht	(event: SubmitEvent) => void		Callback-Funktion. Sie erhält ein `SubmitEvent` mit `submitter` (der auslösende Button oder `null`) sowie `target` (das Formular).
$options	boolean \| AddEventListenerOptions	false	Optionen wie `once`, `capture` oder `signal` (`AbortSignal` zum Entfernen des Listeners).

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Das Standardverhalten verhindert man mit event.preventDefault(). Ein return false wirkt nur bei onsubmit-Handlern.

Beispiele

Formular per fetch absenden, ohne die Seite neu zu laden

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

form.addEventListener('submit', async (event) => {
  event.preventDefault(); // normale Navigation verhindern

  const daten = new FormData(form);
  try {
    const res = await fetch(form.action, {
      method: 'POST',
      body: daten
    });
    if (!res.ok) throw new Error(`HTTP ${res.status}`);
    console.log('Nachricht gesendet');
    form.reset();
  } catch (err) {
    console.error('Senden fehlgeschlagen:', err.message);
  }
});

Nachricht gesendet

Auslösenden Button über submitter erkennen

// <form id="artikel">
//   <button name="aktion" value="entwurf">Entwurf speichern</button>
//   <button name="aktion" value="veroeffentlichen">Veröffentlichen</button>
// </form>
const form = document.querySelector('#artikel');

form.onsubmit = (event) => {
  event.preventDefault();
  const aktion = event.submitter?.value ?? 'unbekannt';
  // submitter mitgeben, damit name/value des Buttons enthalten sind
  const daten = new FormData(form, event.submitter);
  console.log('Aktion:', aktion, daten.get('aktion'));
};

Aktion: veroeffentlichen veroeffentlichen

Doppeltes Absenden verhindern und Listener entfernen

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

const onSubmit = (event) => {
  const button = event.submitter;
  if (button) button.disabled = true; // Doppelklick verhindern
  console.log('Bestellung wird abgeschickt');
};

form.addEventListener('submit', onSubmit);

// Später, z. B. wenn die Komponente abgebaut wird:
form.removeEventListener('submit', onSubmit);

Bestellung wird abgeschickt

requestSubmit() vs. submit()

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

form.addEventListener('submit', (event) => {
  event.preventDefault();
  console.log('submit-Handler ausgeführt');
});

form.requestSubmit(); // prüft das Formular und löst das submit-Ereignis aus
form.submit();        // KEIN Ereignis, keine Prüfung, der Browser navigiert direkt

submit-Handler ausgeführt

// Wichtig · Fallstricke

form.submit() löst kein submit-Ereignis aus und überspringt die eingebaute Formular-Validierung (required, pattern …). Verwende stattdessen form.requestSubmit(submitter?). Das geht in allen modernen Browsern, in Safari ab Version 16.
Das Ereignis wird am <form> ausgelöst, nicht am Button. Ein click-Handler am Button erfasst das Absenden per Enter-Taste nicht.
Ist ein Formular ungültig, feuert submit gar nicht. Stattdessen lösen die betroffenen Felder das Ereignis invalid aus. Mit dem Attribut novalidate am Formular schaltet man die eingebaute Prüfung ab.
Ein <button> ohne type-Attribut hat innerhalb eines Formulars standardmäßig type="submit". Das führt oft zu ungewolltem Absenden. Für reine Aktions-Buttons also type="button" setzen.
return false verhindert das Absenden nur bei onsubmit-Handlern (Eigenschaft oder HTML-Attribut), nicht bei addEventListener. Dort braucht es preventDefault().
SubmitEvent.submitter und new FormData(form, submitter) sind jüngere Ergänzungen. In älteren Browsern (vor allem Safari vor 15.4) kann submitter fehlen. Ohne preventDefault() werden Name und Wert des auslösenden Buttons beim normalen Absenden mitgeschickt.
Sicherheit: Eine Prüfung auf dem Client ersetzt nie die Prüfung auf dem Server. Wer per fetch sendet, braucht trotzdem CSRF-Schutz, zum Beispiel über ein Token im Formular oder SameSite-Cookies.

Siehe auch

SubmitEvent HTMLFormElement.requestSubmit() HTMLFormElement.submit() Event.preventDefault() HTMLFormElement: reset