Cómo detectar cuándo una pestaña del navegador se vuelve inactiva

Tienes un intervalo de polling que se dispara cada diez segundos, un vídeo reproduciéndose en segundo plano o un bucle de animación en ejecución — todos consumiendo recursos para un usuario que cambió de pestaña hace cinco minutos. La solución es sencilla una vez que conoces la API adecuada para utilizar.

La herramienta adecuada: la Page Visibility API

Las soluciones más antiguas dependían de los eventos focus y blur de window — window.onfocus y window.onblur. Estos detectan si la ventana del navegador tiene el foco del teclado, no si la pestaña es realmente visible. En configuraciones de pantalla dividida o flujos de trabajo con múltiples ventanas, una pestaña puede ser completamente visible sin tener el foco, y viceversa. Además, su comportamiento era inconsistente entre navegadores específicamente para el cambio de pestañas.

La Page Visibility API resuelve esto correctamente. Te indica exactamente si la página es visible para el usuario, independientemente del estado del foco.

Dos propiedades te proporcionan el estado actual:

• document.visibilityState — devuelve "visible" o "hidden"
• document.hidden — devuelve true cuando la pestaña está oculta, false cuando es visible

No se necesitan prefijos de proveedor en los navegadores modernos. La API tiene amplio soporte en Chrome, Firefox, Safari y Edge — tanto en escritorio como en móvil.

Escuchando el evento visibilitychange

El evento visibilitychange se dispara en document cada vez que la pestaña se oculta o vuelve a ser visible. Aquí está el patrón básico:

document.addEventListener("visibilitychange", () => {
  if (document.hidden) {
    console.log("Tab is hidden — pause or reduce work");
  } else {
    console.log("Tab is visible — resume work");
  }
});

También puedes leer document.visibilityState directamente si necesitas el valor de cadena en lugar de un booleano.

Casos de uso prácticos

Pausar y reanudar el polling

En lugar de realizar peticiones a la API mientras el usuario está en otra pestaña, pausa el intervalo y reanúdalo cuando regrese:

let intervalId = null;

function startPolling() {
  if (intervalId !== null) return;
  intervalId = setInterval(fetchData, 10000);
}

function stopPolling() {
  clearInterval(intervalId);
  intervalId = null;
}

document.addEventListener("visibilitychange", () => {
  document.hidden ? stopPolling() : startPolling();
});

startPolling();

Nota: los navegadores limitan (throttle) setInterval en pestañas en segundo plano en lugar de detenerlo por completo, por lo que confiar en la precisión temporal en pestañas ocultas es poco fiable de todos modos. Pausar explícitamente es más limpio. Protegerse contra intervalos duplicados también evita que se acumulen múltiples temporizadores si startPolling se llama dos veces.

Pausar la reproducción multimedia

const video = document.querySelector("video");

document.addEventListener("visibilitychange", () => {
  if (document.hidden) {
    video.pause();
  } else {
    video.play().catch(() => {
      // Autoplay may be blocked by the browser; handle silently
    });
  }
});

El manejador .catch() es importante porque video.play() devuelve una promesa que puede rechazarse si el navegador bloquea la reproducción automática, lo que de otro modo generaría un error no capturado.

Guardar automáticamente un borrador de formulario

Activa un guardado cuando el usuario abandona la pestaña en lugar de en un temporizador fijo:

document.addEventListener("visibilitychange", () => {
  if (document.hidden) {
    saveDraft();
  }
});

Enviar analíticas antes de que el usuario abandone la página

Para datos de fin de sesión, combina el evento visibilitychange con pagehide y utiliza navigator.sendBeacon() para enviar datos de forma fiable sin bloquear la navegación:

document.addEventListener("visibilitychange", () => {
  if (document.visibilityState === "hidden") {
    navigator.sendBeacon(
      "/analytics",
      JSON.stringify({ event: "tab_hidden" })
    );
  }
});

window.addEventListener("pagehide", () => {
  navigator.sendBeacon(
    "/analytics",
    JSON.stringify({ event: "page_unload" })
  );
});

Evita el evento unload para este propósito — no es fiable en los navegadores modernos y rompe la caché de avance/retroceso (bfcache), lo que degrada el rendimiento de la navegación. En los navegadores móviles, visibilitychange con el estado "hidden" suele ser la única señal fiable de que una sesión ha terminado, ya que pagehide y beforeunload no siempre se disparan.

Limpiando los event listeners

Elimina siempre los listeners cuando ya no sean necesarios, especialmente en aplicaciones de página única:

function handleVisibility() {
  console.log(document.visibilityState);
}

document.addEventListener("visibilitychange", handleVisibility);

// Later, when tearing down:
document.removeEventListener("visibilitychange", handleVisibility);

Recuerda que la referencia pasada a removeEventListener debe ser exactamente la misma referencia de función utilizada en addEventListener. Las funciones flecha en línea no se pueden eliminar porque cada una crea una nueva referencia.

Conclusión

La Page Visibility API — específicamente document.hidden, document.visibilityState y el evento visibilitychange — es la forma correcta y moderna de detectar cuándo una pestaña del navegador se vuelve inactiva. Funciona de manera fiable en todos los navegadores actuales, maneja el cambio de pestañas con precisión donde los eventos focus y blur de window se quedan cortos, y se combina bien con navigator.sendBeacon() y el evento pagehide para el manejo del final de sesión. Úsala para detener trabajo innecesario, guardar el estado o realizar seguimiento de la interacción, y limpia tus listeners cuando hayas terminado.

Preguntas frecuentes

Understand every bug

Uncover frustrations, understand bugs and fix slowdowns like never before 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.