HTMLInputElement.defaultChecked — Eigenschaft · JavaScript-Referenz

Signatur

HTMLInputElement.defaultChecked

Beschreibung

Die Eigenschaft defaultChecked gibt an, ob ein <input type="checkbox"> oder <input type="radio"> standardmäßig markiert ist. Sie spiegelt direkt das Inhaltsattribut checked wider: Wird defaultChecked = true gesetzt, fügt der Browser das Attribut checked hinzu, bei false entfernt er es.

Wichtig ist der Unterschied zur Eigenschaft checked: checked ist der aktuelle Zustand, den Nutzer durch Anklicken ändern. defaultChecked ist der Ausgangszustand, auf den das Feld beim Zurücksetzen des Formulars (form.reset() oder <button type="reset">) wiederhergestellt wird.

Typische Einsatzfälle sind das Erkennen ungespeicherter Änderungen (Vergleich von checked mit defaultChecked), das Festlegen neuer Ausgangswerte nach erfolgreichem Speichern sowie das dynamische Erzeugen von Formularen, deren Reset-Verhalten korrekt sein soll.

Parameter

Name	Typ	Default	Beschreibung
$value	boolean	false	Beim Setzen: `true` fügt das Attribut `checked` hinzu, `false` entfernt es. Andere Werte werden in einen Boolean umgewandelt.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn das Element das Attribut checked besitzt, sonst false.

Beispiele

Ausgangs- und aktuellen Zustand vergleichen

// HTML: <input type="checkbox" id="newsletter" checked>
const box = document.getElementById('newsletter');

box.checked = false; // simuliert Nutzeraktion

console.log(box.defaultChecked); // Ausgangszustand
console.log(box.checked);        // aktueller Zustand
console.log(box.hasAttribute('checked'));

true false true

Ungespeicherte Änderungen im Formular erkennen

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

const isDirty = () =>
  [...form.querySelectorAll('input[type=checkbox], input[type=radio]')]
    .some((input) => input.checked !== input.defaultChecked);

window.addEventListener('beforeunload', (event) => {
  if (isDirty()) event.preventDefault();
});

Nach dem Speichern neue Ausgangswerte übernehmen

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

form.addEventListener('submit', async (event) => {
  event.preventDefault();
  await fetch('/api/settings', { method: 'POST', body: new FormData(form) });

  // Aktuellen Zustand als neuen Standard festlegen,
  // damit form.reset() nicht auf alte Werte zurückspringt
  form.querySelectorAll('input[type=checkbox]').forEach((box) => {
    box.defaultChecked = box.checked;
  });
});

Dynamisch erzeugte Checkbox mit korrektem Reset

const form = document.createElement('form');
const box = document.createElement('input');
box.type = 'checkbox';
box.defaultChecked = true; // setzt Attribut checked
form.append(box);

box.checked = false;
form.reset();
console.log(box.checked);

true

// Wichtig · Fallstricke

Nicht mit checked verwechseln: Das Ändern von checked verändert weder defaultChecked noch das HTML-Attribut. Wer Formulare per innerHTML oder outerHTML serialisiert, sieht daher nur den Ausgangszustand.
Dirty-Flag: Solange checked weder vom Nutzer noch per Skript geändert wurde, wirkt das Setzen von defaultChecked sofort auch auf checked. Danach nicht mehr – erst ein form.reset() gleicht beide wieder an.
Bei Radiogruppen können mehrere Buttons defaultChecked sein; beim Reset gewinnt der letzte markierte in Dokumentreihenfolge.
Bei anderen Input-Typen (z. B. text) ist die Eigenschaft vorhanden, hat aber keine sichtbare Wirkung.
Wird in allen Browsern seit Langem unterstützt.

Siehe auch

HTMLInputElement.checked HTMLInputElement.defaultValue HTMLInputElement.indeterminate HTMLFormElement.reset() HTMLOptionElement.defaultSelected HTMLInputElement HTMLInputElement.multiple