Como Detectar o Status Online e Offline em JavaScript

Sua aplicação parece funcionar bem — até que um usuário perde a conexão no meio de uma sessão e nada mais funciona. Detectar o status online e offline em JavaScript permite que você responda de forma elegante: exiba um banner de aviso, pause requisições de rede ou tente novamente automaticamente quando a conectividade retornar. Veja como fazer isso de forma confiável.

A Resposta Rápida: navigator.onLine e Eventos da Window

O navegador expõe duas ferramentas para detecção online/offline em JavaScript:

• navigator.onLine — uma propriedade booleana que você pode ler a qualquer momento
• eventos online e offline da window — disparados quando o status de conectividade muda

Juntos, eles cobrem os dois cenários que importam: verificar o status no carregamento da página e reagir quando ele muda.

Lendo navigator.onLine no Carregamento da Página

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

Isso é útil para definir o estado inicial da UI quando a página carrega pela primeira vez — por exemplo, desabilitar um botão “Sincronizar” se o usuário já estiver offline.

Ouvindo Eventos Online e Offline em JavaScript

Fazer polling de navigator.onLine em um timer é desperdício. Em vez disso, use os eventos online e offline na 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
})

Esses eventos são disparados automaticamente quando o navegador detecta uma mudança no status da rede, então sua aplicação reage imediatamente sem nenhuma sobrecarga de polling.

Exemplo Prático: Exibindo um Banner Offline

Aqui está um padrão mínimo e pronto para produção que combina ambas as abordagens:

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>
  Você está offline. Alguns recursos podem estar indisponíveis.
</div>

Este padrão é limpo, orientado a eventos e evita vazamentos de memória, já que os listeners são anexados uma vez e reutilizam a mesma função manipuladora.

A Limitação Crítica do navigator.onLine

Esta é a parte que a maioria dos tutoriais não explica bem. navigator.onLine não confirma acesso real à internet.

• false é confiável — o navegador está definitivamente offline.
• true significa apenas que o dispositivo está conectado a alguma rede (um roteador, um adaptador VPN, uma LAN). O usuário pode estar atrás de um portal cativo, ou seu backend pode estar inacessível.

Não confie em navigator.onLine retornando true como prova de conectividade. Use-o para indicar que o usuário pode estar offline, não para confirmar que está conectado.

Verificando Conectividade Real com uma Requisição de Rede

Quando navigator.onLine retorna true mas uma operação crítica falha, confirme a acessibilidade com uma requisição leve para seu próprio backend:

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

Use seu próprio endpoint — não uma URL de terceiros — para evitar problemas de CORS. Uma requisição HEAD para uma rota pequena e rápida mantém o impacto na largura de banda mínimo.

Opcional: A API Network Information

Para dicas sobre qualidade de conexão (não apenas online/offline), navigator.connection expõe propriedades como effectiveType ('4g', '3g', 'slow-2g') e downlink. O suporte dos navegadores é limitado a navegadores baseados em Chromium — trate-a apenas como uma melhoria progressiva.

Testando Comportamento Offline no DevTools

Abra o Chrome DevTools → aba Network → defina o dropdown de throttle para Offline. Isso dispara o evento offline e define navigator.onLine como false, permitindo que você teste sua UI sem desconectar sua máquina.

Conclusão

Detectar o status online em JavaScript se resume a três coisas: ler navigator.onLine no carregamento, ouvir eventos online/offline para mudanças e verificar a conectividade real com uma requisição fetch antes de retomar operações críticas. Essa combinação lida com a grande maioria dos cenários de conectividade do mundo real de forma limpa e eficiente.

Perguntas Frequentes

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.