Node.isConnected — Eigenschaft · JavaScript-Referenz

Signatur

Node.isConnected

Beschreibung

Die Eigenschaft isConnected gibt true zurück, wenn der Knoten Teil eines Dokumentbaums ist. Er muss dazu nicht direkt unter dem Document hängen: Es reicht, wenn eine Kette von Elternknoten dorthin führt. Die Kette darf auch über Shadow-Roots laufen. Frisch erzeugte Knoten (document.createElement()), Knoten in einem DocumentFragment oder in einem <template>-Inhalt und entfernte Knoten liefern false.

Häufig braucht man das in Web Components, denn connectedCallback() kann auch dann aufgerufen werden, wenn das Element schon wieder entfernt wurde. Mit this.isConnected lässt sich das vor teurer Initialisierung prüfen. Ebenso nützlich ist die Eigenschaft in asynchronem Code: Ein fetch kann zurückkommen, nachdem das Ziel-Element längst entfernt wurde.

Früher schrieb man dafür document.contains(node) oder document.documentElement.contains(node). Diese Prüfung übersieht aber Knoten in Shadow-DOM-Bäumen, weil contains() keine Shadow-Grenzen überschreitet. isConnected dagegen berücksichtigt den Shadow-including root und ist dadurch in diesem Fall zuverlässiger.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn der Knoten (auch über Shadow-Roots hinweg) mit einem Document verbunden ist, sonst false.

Beispiele

Zustand vor und nach dem Einfügen und Entfernen

const box = document.createElement('div');
console.log(box.isConnected); // noch nicht eingefügt

document.body.append(box);
console.log(box.isConnected);

box.remove();
console.log(box.isConnected);

false true false

Asynchrones Ergebnis nur rendern, wenn das Ziel noch existiert

const loadUserCard = async (container, userId) => {
  const res = await fetch(`/api/users/${userId}`);
  const user = await res.json();

  // Container wurde womöglich inzwischen entfernt (z. B. Seitenwechsel in einer SPA)
  if (!container.isConnected) {
    console.log('Container entfernt – Rendern übersprungen');
    return;
  }
  container.textContent = user.name;
};

loadUserCard(document.querySelector('#user-card'), 42);

Web Component: Initialisierung in connectedCallback absichern

class LiveClock extends HTMLElement {
  connectedCallback() {
    // Kann aufgerufen werden, obwohl das Element schon wieder entfernt wurde
    if (!this.isConnected) return;
    this.timer = setInterval(() => {
      this.textContent = new Date().toLocaleTimeString('de-DE');
    }, 1000);
  }

  disconnectedCallback() {
    clearInterval(this.timer);
  }
}
customElements.define('live-clock', LiveClock);

document.body.append(document.createElement('live-clock'));

Knoten im Shadow DOM: isConnected vs. document.contains()

const host = document.createElement('div');
document.body.append(host);

const shadow = host.attachShadow({ mode: 'open' });
const inner = document.createElement('span');
shadow.append(inner);

console.log(inner.isConnected);
console.log(document.contains(inner)); // contains() überschreitet keine Shadow-Grenzen

true false

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung wie node.isConnected = true wird im Sloppy Mode stillschweigend ignoriert und löst im Strict Mode einen TypeError aus.
Nur eine Momentaufnahme: Die Eigenschaft meldet keine Änderungen von selbst. Wer auf Einfügen oder Entfernen reagieren will, nimmt MutationObserver oder bei Custom Elements connectedCallback und disconnectedCallback.
Anderes Dokument: true heißt nur, dass der Knoten mit irgendeinem Dokument verbunden ist, zum Beispiel mit einem per DOMParser erzeugten Dokument oder einem iframe-Dokument. Ob es das aktuelle Dokument ist, prüft man zusätzlich mit node.ownerDocument === document.
document.isConnected selbst ist immer true. Ein DocumentFragment und die Knoten darin liefern false.
Kompatibilität: Unterstützt in Chrome/Edge 54+, Firefox 49+ und Safari 10+. Im Internet Explorer fehlt die Eigenschaft; als Ersatz dient document.documentElement.contains(node), das aber Shadow DOM nicht berücksichtigt.

Siehe auch

Node.prototype.contains() Node.prototype.getRootNode() Node.parentNode Node.ownerDocument MutationObserver Element.prototype.remove() ImageTrack.selected