Navigator.onLine — Eigenschaft · JavaScript-Referenz

Signatur

Navigator.onLine

Beschreibung

navigator.onLine gibt den Verbindungsstatus des Browsers als boolean zurück. Der Wert ist false, wenn der Browser sicher weiß, dass keine Netzwerkverbindung besteht, etwa weil der Flugmodus aktiv ist, kein WLAN oder LAN verbunden ist oder der Nutzer „Offline arbeiten“ gewählt hat. In allen anderen Fällen ist der Wert true.

Die Eigenschaft eignet sich für Offline-fähige Web-Apps und PWAs. Damit kannst du einen Offline-Hinweis anzeigen, Formulardaten lokal in eine Warteschlange legen (zum Beispiel in IndexedDB) oder Synchronisierungen verschieben, bis die Verbindung wieder da ist. Auf Änderungen des Status reagierst du mit den Ereignissen online und offline am window-Objekt. Das geht per addEventListener oder über die Eigenschaften window.ononline und window.onoffline.

Wichtig: true bedeutet nicht, dass das Internet erreichbar ist. Es heißt nur, dass eine Netzwerkschnittstelle aktiv ist. Ein WLAN ohne Internetzugang, ein Captive Portal (z. B. eine Anmeldeseite im Hotel-WLAN) oder ein ausgefallener Server ergeben trotzdem true. Nur false ist eine verlässliche Aussage. Willst du die echte Erreichbarkeit wissen, schick zusätzlich eine kleine Testanfrage an deinen eigenen Server.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn der Browser eine Netzwerkverbindung vermutet, false, wenn er sicher offline ist. Die Eigenschaft ist schreibgeschützt.

Beispiele

Aktuellen Verbindungsstatus abfragen

const status = navigator.onLine ? 'online' : 'offline';
console.log(`Der Browser ist ${status}.`);

Der Browser ist online.

Offline-Banner mit online/offline-Ereignissen

const banner = document.createElement('div');
banner.textContent = 'Keine Internetverbindung – Änderungen werden später gespeichert.';
banner.hidden = navigator.onLine;
document.body.prepend(banner);

const updateStatus = () => {
  banner.hidden = navigator.onLine;
  console.log('Status geändert:', navigator.onLine ? 'online' : 'offline');
};

window.addEventListener('online', updateStatus);
window.addEventListener('offline', updateStatus);

// Später aufräumen, z. B. beim Entfernen einer Komponente:
// window.removeEventListener('online', updateStatus);
// window.removeEventListener('offline', updateStatus);

Status geändert: offline Status geändert: online

Anfragen offline in eine Warteschlange legen und später senden

const queue = JSON.parse(localStorage.getItem('pendingRequests') ?? '[]');

const saveQueue = () => localStorage.setItem('pendingRequests', JSON.stringify(queue));

const sendOrQueue = async (payload) => {
  if (!navigator.onLine) {
    queue.push(payload);
    saveQueue();
    console.log('Offline – Anfrage vorgemerkt:', queue.length);
    return;
  }
  await fetch('/api/notes', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(payload)
  });
};

window.ononline = async () => {
  while (queue.length) {
    await sendOrQueue(queue.shift());
  }
  saveQueue();
  console.log('Warteschlange abgearbeitet.');
};

sendOrQueue({ text: 'Einkaufsliste aktualisieren' });

Offline – Anfrage vorgemerkt: 1 Warteschlange abgearbeitet.

Echte Erreichbarkeit zusätzlich prüfen

const isReallyOnline = async (url = '/ping', timeout = 3000) => {
  if (!navigator.onLine) return false;
  try {
    const res = await fetch(url, {
      method: 'HEAD',
      cache: 'no-store',
      signal: AbortSignal.timeout(timeout)
    });
    return res.ok;
  } catch {
    return false;
  }
};

console.log('Server erreichbar:', await isReallyOnline());

Server erreichbar: true

// Wichtig · Fallstricke

Kann falsch true melden: Nur false ist verlässlich. Bei einem Captive Portal, einem Router ohne Internetzugang oder einer virtuellen Netzwerkkarte (z. B. von VirtualBox, Docker oder einem VPN) meldet der Browser oft true, obwohl keine Verbindung ins Internet besteht.
Browser verhalten sich unterschiedlich: Firefox hat den Wert früher nur im Modus „Offline arbeiten“ auf false gesetzt. Seit Version 41 berücksichtigt er auch den Netzwerkstatus des Betriebssystems, zumindest unter Windows, Linux und macOS.
Offline simulieren beim Testen: In den Chrome-DevTools kannst du unter „Network“ die Drosselung auf „Offline“ stellen. Dann ändert sich navigator.onLine, und die Ereignisse werden ausgelöst.
Ereignisse am richtigen Objekt: Die Ereignisse online und offline werden am window ausgelöst (in Workern am globalen Objekt self), nicht an navigator.
Serverseitiges Rendern: In Node.js gibt es navigator erst ab Version 21 und dort ohne onLine. Beim serverseitigen Rendern (SSR) solltest du deshalb vorher prüfen, ob die Eigenschaft existiert, z. B. mit typeof navigator !== 'undefined' && 'onLine' in navigator.
Für echte Offline-Fähigkeit: Kombiniere die Eigenschaft mit Service Workern und der Cache API, statt nur auf den Status zu reagieren.

Siehe auch

Navigator Navigator.connection NavigateEvent.info Navigator.ink Navigator.login