Element.toggleAttribute() — Methode · JavaScript-Referenz

Signatur

Element.prototype.toggleAttribute(name, force)

Beschreibung

toggleAttribute() ist die bequemste Art, Boolean-Attribute wie disabled, hidden, readonly, open oder eigene data-*-Schalter zu steuern. Bei HTML-Boolean-Attributen zählt nur, ob das Attribut vorhanden ist, nicht sein Wert. disabled="false" deaktiviert ein Element also trotzdem. Genau dieses Verhalten bildet die Methode ab: Sie fügt das Attribut mit leerem Wert ("") hinzu oder entfernt es ganz.

Ohne zweites Argument wird der aktuelle Zustand umgekehrt. Übergibt man force, arbeitet die Methode wie classList.toggle() mit Zielzustand: Bei true wird das Attribut nur hinzugefügt (falls es fehlt), bei false nur entfernt. So lässt sich ein Zustand direkt aus einer Bedingung ableiten, ohne if/else mit setAttribute() und removeAttribute().

Der Rückgabewert zeigt immer, ob das Attribut nach dem Aufruf vorhanden ist. Das ist nützlich, um zum Beispiel aria-*-Zustände oder die Beschriftung einer Schaltfläche anzupassen.

Parameter

Name	Typ	Default	Beschreibung
$name Pflicht	string		Name des Attributs. Bei HTML-Elementen in HTML-Dokumenten wird er automatisch in Kleinbuchstaben umgewandelt. Ein ungültiger Name löst eine `InvalidCharacterError`-`DOMException` aus.
$force	boolean		Optional. `true`: Attribut nur hinzufügen bzw. beibehalten. `false`: Attribut nur entfernen. Ohne Angabe wird der Zustand umgeschaltet.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn das Attribut nach dem Aufruf vorhanden ist, sonst false.

Beispiele

Eingabefeld per Schaltfläche sperren und entsperren

const input = document.querySelector('#username');
const button = document.querySelector('#lock');

button.addEventListener('click', () => {
  const isDisabled = input.toggleAttribute('disabled');
  button.textContent = isDisabled ? 'Entsperren' : 'Sperren';
  console.log('disabled:', isDisabled);
});

disabled: true (beim zweiten Klick) disabled: false

Zustand mit force aus einer Bedingung ableiten

const form = document.querySelector('form');
const submit = form.querySelector('button[type="submit"]');

form.addEventListener('input', () => {
  // Absenden nur erlauben, wenn das Formular gültig ist
  submit.toggleAttribute('disabled', !form.checkValidity());
});

Rückgabewert und Attributwert prüfen

const panel = document.createElement('div');

console.log(panel.toggleAttribute('hidden'));        // hinzugefügt
console.log(JSON.stringify(panel.getAttribute('hidden')));
console.log(panel.toggleAttribute('hidden', true));  // bleibt erhalten
console.log(panel.toggleAttribute('hidden'));        // entfernt
console.log(panel.hasAttribute('hidden'));

true "" true false false

Aufklappbares details-Element und ARIA synchronisieren

const details = document.querySelector('details');
const toggleBtn = document.querySelector('#toggle-details');

toggleBtn.addEventListener('click', () => {
  const open = details.toggleAttribute('open');
  toggleBtn.setAttribute('aria-expanded', String(open));
});

// Wichtig · Fallstricke

Nur für Boolean-Attribute geeignet: Beim Hinzufügen wird der Wert immer auf "" gesetzt, ein vorhandener Wert geht beim Entfernen verloren. Für Attribute mit Wert (z. B. aria-expanded="true"/"false") nimmst du besser setAttribute(), denn ARIA-Zustände sind keine Boolean-Attribute.
force und Wahrheitswerte: Der Wert wird in einen Boolean umgewandelt. toggleAttribute('hidden', 0) entfernt das Attribut also, und undefined gilt als „nicht angegeben“, schaltet also um.
Attribut vs. Eigenschaft: Bei manchen Elementen spiegeln sich Attribut und DOM-Eigenschaft nicht vollständig. Das Attribut checked legt zum Beispiel nur den Vorgabewert fest. Den aktuellen Zustand steuerst du über input.checked.
Groß- und Kleinschreibung: In HTML-Dokumenten wird name klein geschrieben, in XML/SVG-Kontexten nicht. Für Attribute mit Namensraum gibt es keine toggleAttributeNS()-Variante.
Kompatibilität: Wird von Chrome 69+, Firefox 63+, Safari 12+ und Edge 18+ unterstützt, nicht vom Internet Explorer. Als Ersatzlösung für alte Browser dient hasAttribute() zusammen mit setAttribute() bzw. removeAttribute().
Jeder Aufruf, der etwas ändert, löst bei MutationObserver mit attributes: true einen Eintrag aus.

Siehe auch

Element.setAttribute() Element.removeAttribute() Element.hasAttribute() Element.getAttribute() DOMTokenList.toggle() Element ProcessingInstruction.toggleAttribute()