SubmitEvent — Schnittstelle · JavaScript-Referenz

Signatur

interface SubmitEvent extends Event

Beschreibung

SubmitEvent ist das Ereignisobjekt, das ein <form>-Element beim Absenden auslöst. Es erbt alle Eigenschaften und Methoden von Event (z. B. preventDefault(), target) und ergänzt sie um die Eigenschaft submitter.

submitter verweist auf den Button bzw. das <input type="submit">-Element, das den Versand ausgelöst hat. Wird das Formular ohne Button abgeschickt (z. B. mit Enter in einem Formular ohne Submit-Button oder über form.requestSubmit() ohne Argument), ist der Wert null, bzw. das Formular selbst wird nicht eingetragen. Das ist besonders nützlich bei Formularen mit mehreren Submit-Buttons (z. B. „Speichern“ und „Löschen“), um die gewünschte Aktion zu unterscheiden.

Typischer Einsatz: Formulare per fetch() absenden statt die Seite neu zu laden. Man ruft event.preventDefault() auf, baut mit new FormData(form, event.submitter) die Daten inklusive Name/Wert des auslösenden Buttons und schickt sie asynchron ab.

Ein SubmitEvent kann auch selbst über den Konstruktor new SubmitEvent(type, options) erzeugt werden – meist nur für Tests. Das Ereignis wird nur ausgelöst, wenn die Formularvalidierung erfolgreich war.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses, praktisch immer `"submit"` (nur beim Konstruktor).
$options	object	{}	Optionales Init-Objekt: alle Optionen von `Event` (`bubbles`, `cancelable`, `composed`) plus `submitter` (`HTMLElement \| null`, Standard `null`).

Beispiele

Formular per fetch absenden und Button-Wert mitschicken

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

form.addEventListener('submit', async (event) => {
  event.preventDefault(); // kein Seiten-Neuladen

  // FormData mit submitter übernimmt name/value des geklickten Buttons
  const data = new FormData(form, event.submitter);

  const response = await fetch(form.action, {
    method: 'POST',
    body: data
  });
  console.log('Status:', response.status);
});

Status: 200

Mehrere Submit-Buttons unterscheiden

// <form id="artikel">
//   <button name="aktion" value="speichern">Speichern</button>
//   <button name="aktion" value="loeschen">Löschen</button>
// </form>
const form = document.querySelector('#artikel');

form.onsubmit = (event) => {
  const aktion = event.submitter?.value ?? 'standard';
  if (aktion === 'loeschen' && !confirm('Wirklich löschen?')) {
    event.preventDefault();
    return;
  }
  console.log('Aktion:', aktion);
};

Aktion: speichern

requestSubmit() mit bestimmtem Button auslösen

const form = document.querySelector('#artikel');
const speichernBtn = form.querySelector('button[value="speichern"]');

form.addEventListener('submit', (event) => {
  event.preventDefault();
  console.log(event instanceof SubmitEvent, event.submitter === speichernBtn);
});

// Löst Validierung + submit-Ereignis aus (im Gegensatz zu form.submit())
form.requestSubmit(speichernBtn);

true true

SubmitEvent für Tests selbst erzeugen

const form = document.createElement('form');
const btn = document.createElement('button');
form.append(btn);

form.addEventListener('submit', (e) => {
  console.log(e.type, e.submitter === btn, e.cancelable);
});

const evt = new SubmitEvent('submit', {
  bubbles: true,
  cancelable: true,
  submitter: btn
});
form.dispatchEvent(evt);

submit true true

// Wichtig · Fallstricke

form.submit() löst kein submit-Ereignis aus und überspringt die Validierung. Wer Listener und Validierung braucht, nutzt form.requestSubmit(button?).
submitter kann null sein (Enter-Taste ohne Submit-Button, requestSubmit() ohne Argument, selbst erzeugte Ereignisse) – immer mit ?. absichern.
Der Listener gehört an das <form>, nicht an den Button: Ein click-Listener am Button erfasst das Absenden per Enter-Taste nicht.
Der zweite Parameter von new FormData(form, submitter) wird erst seit etwa 2023 unterstützt (Chrome 112, Firefox 111, Safari 16.4). In älteren Browsern fehlt der Button-Wert in den Daten.
Kompatibilität: SubmitEvent/submitter gibt es seit Chrome 81, Firefox 75 und Safari 15.4. In älteren Safari-Versionen ist das Ereignis ein einfaches Event ohne submitter.
Ein selbst erzeugtes und per dispatchEvent() ausgelöstes SubmitEvent schickt das Formular nicht tatsächlich ab – es ruft nur die Listener auf.

Siehe auch

Event HTMLFormElement HTMLFormElement.requestSubmit() FormData Event.preventDefault()