SubmitEvent.submitter — Eigenschaft · JavaScript-Referenz

Signatur

SubmitEvent.submitter

Beschreibung

Die Eigenschaft submitter ist im submit-Event eines Formulars verfügbar. Sie verweist auf das Element, das das Absenden ausgelöst hat, zum Beispiel ein <button type="submit"> oder ein <input type="submit"> bzw. <input type="image">.

Praktisch ist das vor allem bei Formularen mit mehreren Absende-Buttons, etwa „Speichern“ und „Entwurf speichern“ oder „Freigeben“ und „Ablehnen“. Über event.submitter sieht der Handler, welcher Button gedrückt wurde, und kann dessen name, value oder data-*-Attribute auslesen. Auch Überschreibungen wie formaction, formmethod oder formnovalidate lassen sich so auswerten.

Wird das Formular ohne Absende-Element abgeschickt, ist der Wert null. Das passiert etwa bei form.requestSubmit() ohne Argument. Drückt man in einem Textfeld die Eingabetaste, setzt der Browser dagegen den ersten (Standard-)Absende-Button des Formulars als submitter, sofern es einen gibt.

Rückgabewert

Typ

HTMLElement | null

Beschreibung

Das auslösende Element, typischerweise HTMLButtonElement oder HTMLInputElement. Ohne auslösendes Element ist der Wert null.

Beispiele

Ermitteln, welcher Button gedrückt wurde

// HTML:
// <form id="artikel">
//   <input name="titel" value="Hallo Welt">
//   <button type="submit" name="aktion" value="entwurf">Entwurf</button>
//   <button type="submit" name="aktion" value="veroeffentlichen">Veröffentlichen</button>
// </form>

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

form.addEventListener('submit', (event) => {
  event.preventDefault();
  const button = event.submitter;
  console.log(`Aktion: ${button?.value ?? 'keine'}`);
});

Aktion: veroeffentlichen (nach Klick auf „Veröffentlichen“)

FormData inklusive Button-Wert per fetch senden

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

form.addEventListener('submit', async (event) => {
  event.preventDefault();
  // Zweites Argument: der submitter wird mit name/value in FormData aufgenommen
  const data = new FormData(form, event.submitter);

  // formaction/formmethod des Buttons berücksichtigen
  const url = event.submitter?.formAction || form.action;
  const method = event.submitter?.formMethod || form.method;

  const response = await fetch(url, { method, body: data });
  console.log(response.status, [...data.entries()]);
});

200 [["titel","Hallo Welt"],["aktion","entwurf"]]

requestSubmit() mit und ohne submitter

const form = document.querySelector('#artikel');
const publishBtn = form.querySelector('[value="veroeffentlichen"]');

form.addEventListener('submit', (event) => {
  event.preventDefault();
  console.log(event.submitter ? event.submitter.value : null);
});

form.requestSubmit();           // kein Absende-Element
form.requestSubmit(publishBtn); // Button als submitter

null veroeffentlichen

// Wichtig · Fallstricke

Null-Prüfung: submitter kann null sein, etwa bei requestSubmit() ohne Argument oder in Formularen ohne Absende-Button, wenn man die Eingabetaste drückt. Deshalb optionale Verkettung (?.) verwenden.
form.submit() löst gar kein submit-Event aus. Dort gibt es also auch keinen submitter. Stattdessen requestSubmit() verwenden.
FormData: new FormData(form) enthält den Wert des gedrückten Buttons nicht. Erst mit new FormData(form, event.submitter) wird er aufgenommen. Dieses zweite Argument wird in neueren Browsern unterstützt (Chrome 112+, Firefox 111+, Safari 16.4+).
Der Wert von submitter stammt aus dem Client. Serverseitig muss man ihn deshalb wie jede Nutzereingabe prüfen und darf sich nicht allein darauf verlassen.
Kompatibilität: Safari unterstützt SubmitEvent erst ab 15.4, der Internet Explorer gar nicht. Für ältere Browser kann man den zuletzt geklickten Button über einen click-Handler merken.
Mit new SubmitEvent('submit', { submitter }) erzeugte Events schicken das Formular nicht wirklich ab. Sie lösen nur die Listener aus.

Siehe auch

SubmitEvent HTMLFormElement.prototype.requestSubmit() Event.prototype.preventDefault() HTMLButtonElement PushSubscription.subscriptionId