Element.childElementCount — Eigenschaft · JavaScript-Referenz

Signatur

Element.childElementCount

Beschreibung

childElementCount gibt zurück, wie viele direkte Kind-Elemente ein Element hat. Gezählt werden nur Knoten vom Typ Element (nodeType === 1). Textknoten (auch reine Leerzeichen und Zeilenumbrüche aus der HTML-Formatierung) und Kommentare zählen nicht mit. Der Wert ist identisch mit element.children.length.

Die Eigenschaft stammt aus dem Mixin ParentNode. Deshalb gibt es sie nicht nur auf Element, sondern auch auf Document und DocumentFragment. Auf document ist der Wert normalerweise 1, weil es dort nur das Wurzelelement <html> gibt.

Typische Anwendungsfälle: prüfen, ob ein Container leer ist (z. B. um einen Hinweis wie „Keine Einträge“ anzuzeigen), Listeneinträge zählen, Obergrenzen durchsetzen („maximal 5 Tags“) oder Zähler-Badges aktualisieren. Anders als childNodes.length stört dabei kein Leerraum aus dem Markup.

Der Wert ist live: Bei jedem Zugriff wird der aktuelle Zustand des DOM gelesen. Die Eigenschaft ist schreibgeschützt, eine Zuweisung hat also keine Wirkung.

Rückgabewert

Typ

number

Beschreibung

Eine nicht-negative Ganzzahl (unsigned long) mit der Anzahl der direkten Kind-Elemente. Hat das Element keine Kind-Elemente, ist der Wert 0.

Beispiele

Kind-Elemente zählen, ohne Textknoten mitzuzählen

const list = document.createElement('ul');
list.innerHTML = `
  <li>Äpfel</li>
  <!-- Kommentar -->
  <li>Birnen</li>
  <li>Kirschen</li>
`;

console.log(list.childElementCount); // nur <li>-Elemente
console.log(list.childNodes.length); // inkl. Text- und Kommentarknoten
console.log(list.children.length);   // identisch mit childElementCount

3 9 3

Hinweis bei leerer Liste anzeigen

const todoList = document.createElement('ul');
const emptyHint = document.createElement('p');
emptyHint.textContent = 'Keine Aufgaben vorhanden.';

const updateHint = () => {
  emptyHint.hidden = todoList.childElementCount > 0;
};

updateHint();
console.log('Hinweis versteckt:', emptyHint.hidden);

const item = document.createElement('li');
item.textContent = 'Einkaufen gehen';
todoList.append(item);
updateHint();
console.log('Hinweis versteckt:', emptyHint.hidden);

Hinweis versteckt: false Hinweis versteckt: true

Obergrenze für hinzugefügte Tags

const MAX_TAGS = 3;
const tagContainer = document.createElement('div');

const addTag = (label) => {
  if (tagContainer.childElementCount >= MAX_TAGS) {
    console.warn(`Maximal ${MAX_TAGS} Tags erlaubt – "${label}" wurde ignoriert.`);
    return false;
  }
  const tag = document.createElement('span');
  tag.className = 'tag';
  tag.textContent = label;
  tagContainer.append(tag);
  return true;
};

['js', 'css', 'html', 'node'].forEach(addTag);
console.log(tagContainer.childElementCount);

Maximal 3 Tags erlaubt – "node" wurde ignoriert. 3

Auf DocumentFragment und Document

const fragment = new DocumentFragment();
fragment.append(
  document.createElement('section'),
  'nur Text',
  document.createElement('footer')
);

console.log(fragment.childElementCount); // Text zählt nicht
console.log(document.childElementCount); // nur <html>

2 1

// Wichtig · Fallstricke

Nur direkte Kinder: Verschachtelte Nachfahren werden nicht mitgezählt. Für alle Nachfahren eignet sich z. B. el.querySelectorAll('*').length.
Nicht mit childNodes.length verwechseln: childNodes enthält auch Leerraum-Textknoten und Kommentare. Beim Prüfen auf „leer“ führt das oft zu falschen Ergebnissen. Ein Element mit childElementCount === 0 kann trotzdem Text enthalten. Prüfen Sie dafür zusätzlich textContent.trim().
Schreibgeschützt: Eine Zuweisung wie el.childElementCount = 0 wird stillschweigend ignoriert, im Strict Mode gibt es einen TypeError. Zum Leeren eines Elements eignet sich el.replaceChildren().
Shadow DOM und Slots: Gezählt werden nur die Kinder im Light DOM des Elements. Elemente im Shadow Root oder über <slot> projizierte Inhalte zählen nicht mit. Für den Shadow Root verwenden Sie el.shadowRoot.childElementCount.
<template>: Der Inhalt steckt in template.content (einem DocumentFragment), deshalb liefert template.childElementCount in der Regel 0.
Kompatibilität: Wird von allen modernen Browsern unterstützt. Der Internet Explorer (ab Version 9) kannte die Eigenschaft nur auf Element, nicht auf Document und DocumentFragment. Außerhalb des Browsers steht sie in DOM-Implementierungen wie jsdom zur Verfügung.

Siehe auch

Element.children Node.childNodes Element.firstElementChild Element.lastElementChild Element.replaceChildren() Node.hasChildNodes() Element.customElementRegistry