HTMLButtonElement — Schnittstelle · JavaScript-Referenz

Signatur

interface HTMLButtonElement extends HTMLElement

Beschreibung

Das Interface HTMLButtonElement steht für jedes <button>-Element im Dokument. Es erbt alles von HTMLElement (z. B. click(), focus(), dataset) und ergänzt Eigenschaften, die speziell für Schaltflächen in Formularen gedacht sind. Du erhältst eine Instanz über document.querySelector('button') oder document.createElement('button').

Wichtige Eigenschaften sind:

type: "submit" (Standard), "reset" oder "button". Damit legst du fest, ob der Button ein Formular absendet.
disabled: deaktiviert die Schaltfläche. Sie bekommt dann keinen Fokus mehr und löst kein click aus.
form (nur lesbar): das zugehörige HTMLFormElement oder null.
name und value: werden beim Absenden als Paar mitgeschickt, allerdings nur für den auslösenden Button.
formAction, formMethod, formEnctype, formNoValidate, formTarget: überschreiben die entsprechenden Attribute des Formulars, wenn dieser Button das Absenden auslöst.
labels, validity, validationMessage, willValidate: für Beschriftungen und die Constraint Validation API.
popoverTargetElement / popoverTargetAction: steuern ein Popover ohne JavaScript-Ereignisbehandlung.

Die Methoden checkValidity(), reportValidity() und setCustomValidity(message) stammen aus der Constraint Validation API. Buttons selbst werden zwar nie validiert (willValidate ist immer false), die Methoden gibt es aber aus Gründen der Einheitlichkeit trotzdem.

In der Praxis nutzt du HTMLButtonElement, um Doppelklicks beim Absenden zu verhindern, Ladezustände anzuzeigen, mehrere Absende-Aktionen in einem Formular zu unterscheiden (über SubmitEvent.submitter) oder barrierefreie Umschalter mit aria-pressed zu bauen.

Rückgabewert

Typ

HTMLButtonElement

Beschreibung

Instanz, die ein <button>-Element repräsentiert, z. B. aus document.createElement('button').

Beispiele

Button erzeugen und einfügen

const btn = document.createElement('button');
btn.type = 'button'; // verhindert ungewolltes Absenden
btn.textContent = 'Mehr laden';
btn.addEventListener('click', () => console.log('Lade weitere Einträge …'));
document.body.append(btn);

console.log(btn instanceof HTMLButtonElement, btn.type);

true "button"

Doppeltes Absenden verhindern

// <form id="order"><button type="submit">Bestellen</button></form>
const form = document.querySelector('#order');
const submitBtn = form.querySelector('button[type="submit"]');

form.addEventListener('submit', async (event) => {
  event.preventDefault();
  submitBtn.disabled = true;
  submitBtn.textContent = 'Wird gesendet …';
  try {
    await fetch('/api/order', { method: 'POST', body: new FormData(form) });
    submitBtn.textContent = 'Bestellt ✓';
  } catch {
    submitBtn.disabled = false;
    submitBtn.textContent = 'Erneut versuchen';
  }
});

Mehrere Absende-Buttons unterscheiden

// <form id="doc">
//   <button name="action" value="save">Speichern</button>
//   <button name="action" value="publish" formnovalidate>Veröffentlichen</button>
// </form>
const form = document.querySelector('#doc');

form.addEventListener('submit', (event) => {
  event.preventDefault();
  const button = event.submitter; // HTMLButtonElement
  const data = new FormData(form, button); // enthält action=...
  console.log(button.value, button.formNoValidate, data.get('action'));
});

publish true "publish" (beim Klick auf „Veröffentlichen“)

Umschalt-Button mit aria-pressed

const toggle = document.createElement('button');
toggle.type = 'button';
toggle.textContent = 'Dunkelmodus';
toggle.setAttribute('aria-pressed', 'false');

toggle.addEventListener('click', () => {
  const pressed = toggle.getAttribute('aria-pressed') === 'true';
  toggle.setAttribute('aria-pressed', String(!pressed));
  document.documentElement.classList.toggle('dark', !pressed);
});

document.body.append(toggle);

// Wichtig · Fallstricke

Standardtyp ist submit: Ein <button> ohne type-Attribut sendet innerhalb eines Formulars dieses Formular ab. Für reine Aktions-Buttons solltest du immer type="button" setzen.
disabled ist nicht dasselbe wie aria-disabled: Ein deaktivierter Button verliert den Fokus und wird für Screenreader beim Durchblättern mit der Tabulatortaste unsichtbar. Soll er weiter erreichbar bleiben, nutze aria-disabled="true" und blockiere den Klick selbst.
Deaktivierte Buttons lösen kein click aus und werden beim Absenden nicht mitgeschickt. Ein Aufruf von click() per Skript bewirkt bei disabled ebenfalls nichts.
name/value landen nur dann in den Formulardaten, wenn genau dieser Button das Absenden ausgelöst hat. Bei form.submit() wird kein Button mitgeschickt, bei form.requestSubmit(button) schon.
willValidate ist bei Buttons immer false. setCustomValidity() hat daher keine sichtbare Wirkung.
Kompatibilität: Die Kern-Eigenschaften funktionieren in allen Browsern. popoverTargetElement/popoverTargetAction gehören seit 2024 zur Baseline. command/commandForElement sind sehr neu und nur teilweise unterstützt.
Sicherheit: Setze Beschriftungen mit textContent und nicht mit innerHTML, wenn der Text aus Benutzereingaben stammt (XSS-Gefahr).

Siehe auch

HTMLOptionElement HTMLAudioElement HTMLOutputElement HTMLQuoteElement HTMLAnchorElement