Comment détecter le statut en ligne et hors ligne en JavaScript

Votre application fonctionne parfaitement — jusqu’à ce qu’un utilisateur perde sa connexion en pleine session et que plus rien ne fonctionne. Détecter le statut en ligne et hors ligne en JavaScript vous permet de réagir avec élégance : afficher une bannière d’avertissement, suspendre les requêtes réseau ou réessayer automatiquement lorsque la connectivité revient. Voici comment le faire de manière fiable.

La réponse rapide : navigator.onLine et les événements Window

Le navigateur expose deux outils pour la détection en ligne/hors ligne en JavaScript :

• navigator.onLine — une propriété booléenne que vous pouvez lire à tout moment
• Les événements online et offline de window — déclenchés lorsque le statut de connectivité change

Ensemble, ils couvrent les deux scénarios qui vous intéressent : vérifier le statut au chargement de la page et réagir lorsqu’il change.

Lecture de navigator.onLine au chargement de la page

if (navigator.onLine) {
  console.log('Browser reports online')
} else {
  console.log('Browser reports offline')
}

Ceci est utile pour définir l’état initial de l’interface utilisateur lors du premier chargement de la page — par exemple, désactiver un bouton « Synchroniser » si l’utilisateur est déjà hors ligne.

Écoute des événements Online et Offline en JavaScript

Interroger navigator.onLine avec un timer est inefficace. Utilisez plutôt les événements online et offline sur window :

window.addEventListener('online', () => {
  console.log('Connection restored')
  // Re-enable UI, retry pending requests
})

window.addEventListener('offline', () => {
  console.log('Connection lost')
  // Show offline banner, disable network actions
})

Ces événements se déclenchent automatiquement lorsque le navigateur détecte un changement de statut réseau, permettant à votre application de réagir immédiatement sans aucune surcharge liée à l’interrogation périodique.

Exemple pratique : affichage d’une bannière hors ligne

Voici un pattern minimal et prêt pour la production qui combine les deux approches :

const banner = document.getElementById('offline-banner')

function updateOnlineStatus() {
  banner.hidden = navigator.onLine
}

// Set initial state
updateOnlineStatus()

// React to changes
window.addEventListener('online', updateOnlineStatus)
window.addEventListener('offline', updateOnlineStatus)

<div id="offline-banner" hidden>
  You're offline. Some features may be unavailable.
</div>

Ce pattern est propre, piloté par les événements et évite les fuites de mémoire puisque les écouteurs sont attachés une seule fois et réutilisent la même fonction de gestion.

La limitation critique de navigator.onLine

C’est la partie que la plupart des tutoriels sous-expliquent. navigator.onLine ne confirme pas un accès réel à Internet.

• false est fiable — le navigateur est définitivement hors ligne.
• true signifie seulement que l’appareil est connecté à un réseau (un routeur, un adaptateur VPN, un réseau local). L’utilisateur pourrait être derrière un portail captif, ou votre backend pourrait être inaccessible.

Ne faites pas confiance à navigator.onLine retournant true comme preuve de connectivité. Utilisez-le pour indiquer que l’utilisateur pourrait être hors ligne, pas pour confirmer qu’il est connecté.

Vérification de la connectivité réelle avec une requête réseau

Lorsque navigator.onLine retourne true mais qu’une opération critique échoue, confirmez l’accessibilité avec une requête légère vers votre propre backend :

async function isReachable() {
  try {
    const response = await fetch('/health-check', {
      method: 'HEAD',
      cache: 'no-store',
    })
    return response.ok
  } catch {
    return false
  }
}

Utilisez votre propre endpoint — pas une URL tierce — pour éviter les problèmes CORS. Une requête HEAD vers une route petite et rapide maintient l’impact sur la bande passante au minimum.

Optionnel : l’API Network Information

Pour obtenir des indications sur la qualité de connexion (pas seulement en ligne/hors ligne), navigator.connection expose des propriétés comme effectiveType ('4g', '3g', 'slow-2g') et downlink. La prise en charge par les navigateurs est limitée aux navigateurs basés sur Chromium — traitez-la uniquement comme une amélioration progressive.

Test du comportement hors ligne dans les DevTools

Ouvrez Chrome DevTools → onglet Network → définissez le menu déroulant de limitation à Offline. Cela déclenche l’événement offline et définit navigator.onLine à false, vous permettant de tester votre interface utilisateur sans déconnecter votre machine.

Conclusion

Détecter le statut en ligne en JavaScript se résume à trois choses : lire navigator.onLine au chargement, écouter les événements online/offline pour les changements, et vérifier la connectivité réelle avec une requête fetch avant de reprendre les opérations critiques. Cette combinaison gère la grande majorité des scénarios de connectivité réels de manière propre et efficace.

FAQ

Complete picture for complete understanding

Capture every clue your frontend is leaving so you can instantly get to the root cause of any issue with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data.

Check our GitHub repo and join the thousands of developers in our community.