Window: offline — Ereignis · JavaScript-Referenz

Signatur

window.addEventListener("offline", handler)

Beschreibung

Das offline-Event des Window-Interfaces wird ausgelöst, sobald der Browser feststellt, dass er keinen Zugriff mehr auf das Netzwerk hat. Gleichzeitig wechselt navigator.onLine auf false. Das Gegenstück ist das online-Event, das beim Wiederherstellen der Verbindung feuert.

Typische Einsatzfälle sind Offline-Hinweise in der Benutzeroberfläche, das Pausieren von Synchronisierungen oder Polling sowie das Zwischenspeichern von Formulardaten oder Aktionen (z. B. in IndexedDB), um sie später nachzusenden. In Progressive Web Apps ergänzt das Event die Offline-Fähigkeiten eines Service Workers.

Der Handler lässt sich per window.addEventListener("offline", handler) oder über die Eigenschaft window.onoffline registrieren. Auch <body onoffline="..."> funktioniert. Das Event ist ein einfaches Event ohne Zusatzdaten, ist nicht abbrechbar und steigt nicht auf (kein Bubbling).

Wichtig: „Offline“ bedeutet nur, dass der Browser keine Netzwerkschnittstelle mehr nutzen kann. Ob ein bestimmter Server wirklich erreichbar ist, sagt das Event nicht aus. Umgekehrt heißt navigator.onLine === true nicht, dass tatsächlich Internetzugang besteht.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Event-Typ, hier immer `"offline"`.
$handler Pflicht	(event: Event) => void		Callback, der beim Verlust der Verbindung aufgerufen wird. Erhält ein einfaches `Event`-Objekt ohne Zusatzdaten.
$options	boolean \| AddEventListenerOptions	false	Optionale Einstellungen wie `once`, `passive` oder `signal` (zum Entfernen per `AbortController`).

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Der Handler erhält ein Event mit type === "offline".

Beispiele

Offline-Banner ein- und ausblenden

const banner = document.querySelector('#offline-banner');

const updateStatus = () => {
  banner.hidden = navigator.onLine;
  console.log(navigator.onLine ? 'Wieder online' : 'Offline – Änderungen werden lokal gespeichert');
};

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

// Beim Laden den aktuellen Zustand prüfen
updateStatus();

Offline – Änderungen werden lokal gespeichert

Über die on-Property registrieren und wieder entfernen

window.onoffline = (event) => {
  console.log(`Event: ${event.type}, onLine = ${navigator.onLine}`);
};

// Später deaktivieren
setTimeout(() => {
  window.onoffline = null;
}, 60_000);

Event: offline, onLine = false

Polling pausieren und per AbortController aufräumen

const controller = new AbortController();
let timerId = null;

const startPolling = () => {
  if (timerId) return;
  timerId = setInterval(async () => {
    try {
      const res = await fetch('/api/nachrichten');
      console.log('Neue Daten:', await res.json());
    } catch (err) {
      console.warn('Abruf fehlgeschlagen:', err.message);
    }
  }, 10_000);
};

const stopPolling = () => {
  clearInterval(timerId);
  timerId = null;
  console.log('Polling pausiert (offline)');
};

window.addEventListener('offline', stopPolling, { signal: controller.signal });
window.addEventListener('online', startPolling, { signal: controller.signal });
if (navigator.onLine) startPolling();

// Beim Verlassen der Ansicht alle Listener entfernen
const destroy = () => {
  controller.abort();
  stopPolling();
};

Polling pausiert (offline)

Removal mit removeEventListener

const handleOffline = () => console.log('Verbindung verloren');

window.addEventListener('offline', handleOffline);

// Nur mit derselben Funktionsreferenz entfernbar
window.removeEventListener('offline', handleOffline);

// Wichtig · Fallstricke

Unzuverlässige Erkennung: Browser melden „offline“ meist nur, wenn keine Netzwerkschnittstelle aktiv ist (z. B. WLAN aus, Flugmodus). Ein verbundenes WLAN ohne Internet, ein Captive Portal oder ein ausgefallener Server lösen in der Regel kein offline-Event aus. Für echte Erreichbarkeit zusätzlich einen Test-Request (z. B. fetch mit Timeout) oder die Fehlerbehandlung von Requests auswerten.
Anfangszustand: Das Event feuert nur beim Wechsel. Beim Laden der Seite immer zusätzlich navigator.onLine prüfen.
Nur am window: Listener an document oder document.body werden (außer über das onoffline-Attribut am <body>, das auf window weitergeleitet wird) nicht zuverlässig ausgelöst, da das Event nicht aufsteigt. In Workern steht das Event am WorkerGlobalScope zur Verfügung.
Entwicklertools: In Chrome/Edge/Firefox lässt sich das Event über die Netzwerk-Drosselung („Offline“) in den DevTools testen.
Kompatibilität: In allen modernen Browsern unterstützt; ältere Firefox-Versionen feuerten es nur beim manuellen „Offline arbeiten“-Modus.

Siehe auch

Navigator.onLine Element: mousewheel Window: online Window: resize Window: blur Window: afterprint