Element.getElementsByClassName() — Methode · JavaScript-Referenz

Signatur

Element.prototype.getElementsByClassName(classNames)

Beschreibung

Die Methode getElementsByClassName() durchsucht den Teilbaum unterhalb des Elements, auf dem sie aufgerufen wird, und liefert alle Nachfahren, die sämtliche übergebenen Klassen besitzen. Das Element selbst wird dabei nie berücksichtigt, auch wenn es die Klasse trägt.

Mehrere Klassennamen werden durch Leerzeichen getrennt in einem einzigen String übergeben, z. B. 'btn primary'. Die Reihenfolge spielt keine Rolle: Ein Element wird nur dann aufgenommen, wenn es alle Klassen hat (UND-Verknüpfung). Im Standardmodus wird zwischen Groß- und Kleinschreibung unterschieden.

Das Ergebnis ist eine Live-Collection: Fügt man später passende Elemente hinzu oder entfernt Klassen, spiegelt sich das sofort in der Collection wider. Das ist praktisch zum wiederholten Abfragen ohne erneuten Aufruf, kann aber beim Iterieren und gleichzeitigen Verändern zu Überraschungen führen.

Für komplexere Auswahlen (Kombination mit Tag, Attributen, Hierarchie) oder wenn eine statische Momentaufnahme gewünscht ist, ist querySelectorAll() meist die bessere Wahl. getElementsByClassName() ist dafür in der Regel etwas schneller und liefert direkt aktuelle Ergebnisse.

Parameter

Name	Typ	Default	Beschreibung
$classNames Pflicht	string		Ein oder mehrere Klassennamen, durch Leerzeichen (Whitespace) getrennt. Nur Elemente mit allen genannten Klassen werden aufgenommen. Kein Punkt-Präfix wie bei CSS-Selektoren verwenden.

Rückgabewert

Typ

HTMLCollection

Beschreibung

Eine live aktualisierte HTMLCollection der passenden Nachfahren in Dokumentreihenfolge. Ist nichts passend, ist die Collection leer (length === 0) — es wird nie null zurückgegeben.

Beispiele

Elemente mit einer Klasse innerhalb eines Containers finden

// HTML: <ul id="todo"><li class="item done">A</li><li class="item">B</li><li class="item done">C</li></ul>
const list = document.getElementById('todo');
const done = list.getElementsByClassName('done');

console.log(done.length);
for (const el of done) {
  console.log(el.textContent);
}

2 A C

Mehrere Klassen kombinieren (UND-Verknüpfung)

// HTML: <form id="f"><button class="btn primary">OK</button><button class="btn">Abbrechen</button></form>
const form = document.getElementById('f');
const primaryButtons = form.getElementsByClassName('primary btn');

console.log(primaryButtons.length, primaryButtons[0].textContent);

1 OK

Live-Verhalten beachten: rückwärts iterieren beim Entfernen von Klassen

const container = document.getElementById('todo');
const active = container.getElementsByClassName('active');

// FALSCH: vorwärts iterieren überspringt Elemente, weil die Collection schrumpft
// for (let i = 0; i < active.length; i++) active[i].classList.remove('active');

// RICHTIG: rückwärts iterieren ...
for (let i = active.length - 1; i >= 0; i--) {
  active[i].classList.remove('active');
}

// ... oder vorher eine statische Kopie erstellen
// Array.from(active).forEach((el) => el.classList.remove('active'));

console.log(active.length);

In ein Array umwandeln, um Array-Methoden zu nutzen

const table = document.querySelector('table');
const prices = [...table.getElementsByClassName('price')];

const total = prices
  .map((cell) => Number.parseFloat(cell.textContent))
  .reduce((sum, value) => sum + value, 0);

console.log(`Summe: ${total.toFixed(2)} €`);

Summe: 59.97 €

// Wichtig · Fallstricke

Live-Collection: Wer beim Durchlaufen Klassen entfernt oder Elemente löscht, verändert die Collection während der Schleife und überspringt Einträge. Rückwärts iterieren oder mit Array.from() kopieren.
Keine Array-Methoden: HTMLCollection besitzt weder forEach() noch map(). for...of funktioniert, für Array-Methoden vorher mit Array.from() oder Spread-Syntax umwandeln.
Kein CSS-Selektor: getElementsByClassName('.foo') findet nichts — den Punkt weglassen.
Das Element selbst wird nie mitgeliefert, nur Nachfahren.
Groß-/Kleinschreibung wird unterschieden; nur im Quirks-Modus wird ASCII-Groß-/Kleinschreibung ignoriert.
Kompatibilität: in allen modernen Browsern verfügbar (Internet Explorer ab Version 9). Auch als Document.getElementsByClassName() für das ganze Dokument vorhanden.

Siehe auch

Document.getElementsByClassName() Element.querySelectorAll() Element.getElementsByTagName() Element.classList HTMLCollection Element.closest()