Cómo Detectar el Estado Online y Offline en JavaScript

Tu aplicación se ve bien, hasta que un usuario pierde su conexión a mitad de sesión y nada funciona. Detectar el estado online y offline en JavaScript te permite responder de manera elegante: mostrar un banner de advertencia, pausar solicitudes de red o reintentar automáticamente cuando la conectividad regrese. Aquí te mostramos cómo hacerlo de manera confiable.

La Respuesta Rápida: navigator.onLine y Eventos de Window

El navegador expone dos herramientas para la detección online/offline en JavaScript:

• navigator.onLine — una propiedad booleana que puedes leer en cualquier momento
• Eventos online y offline de window — se disparan cuando cambia el estado de conectividad

Juntos, cubren los dos escenarios que te importan: verificar el estado al cargar la página y reaccionar cuando cambia.

Leer navigator.onLine al Cargar la Página

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

Esto es útil para establecer el estado inicial de la UI cuando la página se carga por primera vez — por ejemplo, deshabilitar un botón de “Sincronizar” si el usuario ya está offline.

Escuchar Eventos Online y Offline en JavaScript

Consultar navigator.onLine con un temporizador es un desperdicio. En su lugar, usa los eventos online y offline en 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
})

Estos eventos se disparan automáticamente cuando el navegador detecta un cambio en el estado de la red, por lo que tu aplicación reacciona inmediatamente sin ninguna sobrecarga de consultas repetitivas.

Ejemplo Práctico: Mostrar un Banner de Offline

Aquí hay un patrón mínimo y listo para producción que combina ambos enfoques:

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>

Este patrón es limpio, basado en eventos y evita fugas de memoria ya que los listeners se adjuntan una vez y reutilizan la misma función manejadora.

La Limitación Crítica de navigator.onLine

Esta es la parte que la mayoría de los tutoriales no explican suficientemente. navigator.onLine no confirma acceso real a internet.

• false es confiable — el navegador está definitivamente offline.
• true solo significa que el dispositivo está conectado a alguna red (un router, un adaptador VPN, una LAN). El usuario podría estar detrás de un portal cautivo, o tu backend podría ser inaccesible.

No confíes en que navigator.onLine devuelva true como prueba de conectividad. Úsalo para indicar que el usuario podría estar offline, no para confirmar que está conectado.

Verificar Conectividad Real con una Solicitud de Red

Cuando navigator.onLine devuelve true pero una operación crítica falla, confirma la accesibilidad con una solicitud ligera a tu propio backend:

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

Usa tu propio endpoint — no una URL de terceros — para evitar problemas de CORS. Una solicitud HEAD a una ruta pequeña y rápida mantiene el impacto en el ancho de banda al mínimo.

Opcional: La API de Network Information

Para obtener indicios sobre la calidad de la conexión (no solo online/offline), navigator.connection expone propiedades como effectiveType ('4g', '3g', 'slow-2g') y downlink. El soporte del navegador está limitado a navegadores basados en Chromium — trátalo solo como una mejora progresiva.

Probar el Comportamiento Offline en DevTools

Abre Chrome DevTools → pestaña Network → establece el menú desplegable de throttle en Offline. Esto activa el evento offline y establece navigator.onLine en false, permitiéndote probar tu UI sin desconectar tu máquina.

Conclusión

Detectar el estado online en JavaScript se reduce a tres cosas: leer navigator.onLine al cargar, escuchar los eventos online/offline para cambios, y verificar la conectividad real con una solicitud fetch antes de reanudar operaciones críticas. Esa combinación maneja la gran mayoría de escenarios de conectividad del mundo real de manera limpia y eficiente.

Preguntas Frecuentes

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.