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

Posso usar navigator.onLine para confirmar que o usuário tem acesso à internet?

Não. navigator.onLine retornando true significa apenas que o dispositivo está conectado a alguma rede, como um roteador ou adaptador VPN. Não garante acesso real à internet. O usuário pode estar atrás de um portal cativo ou seu servidor pode estar fora do ar. Sempre verifique com uma requisição de rede real para operações críticas.

Os eventos online e offline funcionam em todos os principais navegadores?

Sim. Os eventos online e offline da window e a propriedade navigator.onLine são suportados em todos os navegadores modernos, incluindo Chrome, Firefox, Safari e Edge. Eles fazem parte da especificação HTML e têm amplo suporte há muitos anos.

Como devo verificar a conectividade real em uma aplicação de produção?

Envie uma requisição fetch leve, como uma requisição HEAD, para um endpoint de health-check no seu próprio servidor. Use cache no-store para ignorar o cache do navegador. Se a requisição for bem-sucedida e retornar um status ok, o usuário tem conectividade genuína. Evite fazer ping em URLs de terceiros para prevenir problemas de CORS.

A API Network Information é confiável para detectar qualidade de conexão?

A API Network Information fornece dicas úteis como tipo de conexão efetiva e velocidade de downlink, mas o suporte dos navegadores é limitado a navegadores baseados em Chromium. Safari e Firefox não a suportam. Trate-a como uma melhoria progressiva e sempre forneça comportamento de fallback para navegadores não suportados.