HTMLInputElement.checked — Eigenschaft · JavaScript-Referenz

Signatur

HTMLInputElement.checked

Beschreibung

Die Eigenschaft checked spiegelt den aktuellen Markierungszustand eines Kontrollkästchens oder Optionsfelds wider. Sie ist lesbar und beschreibbar: Beim Lesen erhält man true oder false, beim Setzen ändert man den Zustand direkt, ohne dass der Nutzer klicken muss.

Wichtig ist der Unterschied zum HTML-Attribut checked: Das Attribut legt nur den Anfangszustand fest und wird über defaultChecked abgebildet. Sobald der Nutzer interagiert oder das Skript checked setzt, laufen Eigenschaft und Attribut auseinander. getAttribute("checked") liefert deshalb nicht den aktuellen Zustand.

Bei Optionsfeldern (type="radio") mit gleichem name innerhalb desselben Formulars gilt: Wird ein Feld per checked = true markiert, heben alle anderen Felder der Gruppe ihre Markierung automatisch auf. Für andere Eingabetypen (z. B. text) hat die Eigenschaft keine sichtbare Wirkung.

Typische Einsätze sind „Alle auswählen“-Schalter, das Auswerten von Einstellungen vor dem Absenden und das Wiederherstellen gespeicherter Formularzustände.

Parameter

Name	Typ	Default	Beschreibung
$value	boolean		Beim Setzen: `true` markiert das Element, `false` hebt die Markierung auf. Andere Werte werden in einen Boolean umgewandelt.

Beispiele

Zustand eines Kontrollkästchens auslesen

// <input type="checkbox" id="newsletter">
const box = document.querySelector('#newsletter');

box.addEventListener('change', () => {
  console.log(box.checked ? 'Newsletter abonniert' : 'Newsletter abbestellt');
});

Newsletter abonniert

„Alle auswählen“-Schalter

// <input type="checkbox" id="alle">
// <input type="checkbox" class="eintrag"> ... (mehrere)
const alle = document.querySelector('#alle');
const eintraege = document.querySelectorAll('.eintrag');

alle.addEventListener('change', () => {
  eintraege.forEach((cb) => { cb.checked = alle.checked; });
});

// Hauptschalter synchron halten
eintraege.forEach((cb) => cb.addEventListener('change', () => {
  const markiert = [...eintraege].filter((e) => e.checked).length;
  alle.checked = markiert === eintraege.length;
  alle.indeterminate = markiert > 0 && markiert < eintraege.length;
}));

Gewähltes Optionsfeld einer Gruppe ermitteln

// <input type="radio" name="versand" value="standard" checked>
// <input type="radio" name="versand" value="express">
const gewaehlt = [...document.querySelectorAll('input[name="versand"]')]
  .find((r) => r.checked);
console.log(gewaehlt?.value);

// Programmatisch umschalten – das andere Feld wird automatisch abgewählt
document.querySelector('input[value="express"]').checked = true;
console.log(document.querySelector('input[value="standard"]').checked);

standard false

Eigenschaft vs. Attribut

// <input type="checkbox" id="agb" checked>
const agb = document.querySelector('#agb');
agb.checked = false;

console.log(agb.checked);               // aktueller Zustand
console.log(agb.defaultChecked);        // Anfangszustand
console.log(agb.hasAttribute('checked'));

false true true

// Wichtig · Fallstricke

Kein Event beim Setzen: Wenn checked per Skript geändert wird, werden weder change noch input ausgelöst. Bei Bedarf manuell mit el.dispatchEvent(new Event('change', { bubbles: true })) auslösen.
Attribut ≠ Zustand: getAttribute('checked') und der CSS-Selektor [checked] geben nur den Anfangszustand wieder. Für den aktuellen Zustand in CSS die Pseudoklasse :checked verwenden.
Formular-Reset: form.reset() setzt checked auf den Wert von defaultChecked zurück.
indeterminate: Der „unbestimmte“ Zustand ist rein visuell und unabhängig von checked; nicht markierte Kontrollkästchen werden beim Absenden nicht mitgesendet – unabhängig von indeterminate.
Bei Radio-Gruppen lässt sich eine Auswahl durch Klick nicht aufheben, wohl aber per checked = false im Skript.
Kompatibilität: in allen Browsern seit jeher unterstützt.

Siehe auch

HTMLInputElement.capture HTMLInputElement.height HTMLInputElement.accept HTMLInputElement.disabled HTMLInputElement.files