useWindowSize — Rastrea las dimensiones de la ventana de forma reactiva con actualizaciones debounce

Receta

import { useState, useEffect, useCallback, useRef } from "react";
 
interface WindowSize {
  width: number;
  height: number;
}
 
interface UseWindowSizeOptions {
  /** Retraso de debounce en ms. Predeterminado: 100 */
  debounceDelay?: number;
  /** Tamaño inicial para SSR. Predeterminado: { width: 0, height: 0 } */
  initialSize?: WindowSize;
}
 
function useWindowSize(options: UseWindowSizeOptions = {}): WindowSize {
  const {
    debounceDelay = 100,
    initialSize = { width: 0, height: 0 },
  } = options;
 
  const [size, setSize] = useState<WindowSize>(() => {
    if (typeof window === "undefined") return initialSize;
    return {
      width: window.innerWidth,
      height: window.innerHeight,
    };
  });
 
  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
 
  useEffect(() => {
    if (typeof window === "undefined") return;
 
    const handleResize = () => {
      if (timerRef.current) clearTimeout(timerRef.current);
 
      timerRef.current = setTimeout(() => {
        setSize({
          width: window.innerWidth,
          height: window.innerHeight,
        });
        timerRef.current = null;
      }, debounceDelay);
    };
 
    // Establecer tamaño inicial al montarse
    setSize({
      width: window.innerWidth,
      height: window.innerHeight,
    });
 
    window.addEventListener("resize", handleResize);
    return () => {
      window.removeEventListener("resize", handleResize);
      if (timerRef.current) clearTimeout(timerRef.current);
    };
  }, [debounceDelay]);
 
  return size;
}

Cuándo usarlo: Necesitas dimensiones de ventana en JavaScript para cálculos de diseño responsivo, dimensionamiento de canvas, listas virtualizadas o renderizado condicional que las media queries de CSS no pueden manejar.

Ejemplo práctico

"use client";
 
function ResponsiveLayout() {
  const { width, height } = useWindowSize();
 
  const columns = width >= 1024 ? 3 : width >= 640 ? 2 : 1;
 
  return (
    <div>
      <p>
        Ventana: {width} x {height}
      </p>
      <div
        style={{
          display: "grid",
          gridTemplateColumns: `repeat(${columns}, 1fr)`,
          gap: 16,
        }}
      >
        {Array.from({ length: 6 }, (_, i) => (
          <div
            key={i}
            style={{
              padding: 24,
              background: "#f5f5f5",
              borderRadius: 8,
              textAlign: "center",
            }}
          >
            Tarjeta {i + 1}
          </div>
        ))}
      </div>
    </div>
  );
}
 
function CanvasSizer() {
  const { width } = useWindowSize({ debounceDelay: 200 });
 
  const canvasWidth = Math.min(width - 32, 800);
  const canvasHeight = canvasWidth * 0.5625; // 16:9
 
  return (
    <canvas
      width={canvasWidth}
      height={canvasHeight}
      style={{ border: "1px solid #ccc" }}
    />
  );
}

Qué demuestra esto:

• El número de columnas de la cuadrícula se adapta según los puntos de corte del ancho de la ventana
• El canvas mantiene una relación de aspecto 16:9 relativa al ancho de la ventana
• El debounce evita re-renderizados excesivos durante el arrastre de cambio de tamaño
• Retraso de debounce personalizado para el componente canvas (200 ms)

Profundización

Cómo funciona

• Inicializador perezoso: useState lee window.innerWidth y window.innerHeight solo en el cliente, retrocediendo a initialSize durante SSR.
• Manejador de cambio de tamaño debounceado: Un debounce basado en setTimeout colapsa eventos de cambio de tamaño rápidos en una única actualización de estado, previniendo jank.
• Limpieza: El listener de evento y cualquier temporizador pendiente se limpian al desmontarse.
• Re-sincronización al montarse: El efecto establece inmediatamente el tamaño actual para manejar casos donde la ventana fue redimensionada mientras el componente estaba desmontado.

Parámetros y valores de retorno

Variaciones

Sin debounce: Para actualizaciones inmediatas (p. ej., vistas previas de cambio de tamaño por arrastre), establece debounceDelay: 0 o elimina setTimeout:

const size = useWindowSize({ debounceDelay: 0 });

Con orientación: Detecta paisaje vs. retrato:

function useOrientation() {
  const { width, height } = useWindowSize();
  return width > height ? "landscape" : "portrait";
}

Tamaño del documento (altura de desplazamiento): Rastrea la altura total del documento en lugar del viewport:

// Dentro del manejador de cambio de tamaño:
setSize({
  width: document.documentElement.scrollWidth,
  height: document.documentElement.scrollHeight,
});

Notas de TypeScript

• La interfaz WindowSize se exporta para que los consumidores puedan escribir su propio estado o props.
• No se necesitan genéricos; el tipo de retorno es siempre { width: number; height: number }.
• La interfaz de opciones utiliza propiedades opcionales con valores predeterminados desestructurados en el cuerpo de la función.

Trampas

• Desincronización de hidratación de SSR — El servidor renderiza con initialSize (0x0), pero el cliente se actualiza inmediatamente a dimensiones reales. Solución: Esto causa un cambio de diseño en la primera renderización. Para diseños críticos, prefiere media queries de CSS o proporciona una estimación razonable de initialSize.
• Actualizaciones demasiado frecuentes — Sin debounce, cada píxel de un arrastre de cambio de tamaño dispara una re-renderización. Solución: El debounce incorporado maneja esto; ajusta debounceDelay según sea necesario.
• Teclado virtual en móvil — En móvil, abrir el teclado redimensiona el viewport y dispara el manejador. Solución: Usa la API window.visualViewport si necesitas distinguir el teclado del cambio de tamaño.
• Contexto de iframe — Dentro de un iframe, window.innerWidth refleja el tamaño del iframe, no de la ventana padre. Solución: Usa parent.window si la política entre orígenes lo permite, o pasa el tamaño como prop.

Alternativas

Preguntas frecuentes

const size = useWindowSize({ debounceDelay: 0 });

function useOrientation(): "landscape" | "portrait" {
  const { width, height } = useWindowSize();
  return width > height ? "landscape" : "portrait";
}

Relacionado

• useMediaQuery — verificaciones de punto de corte booleanas
• useDebounce — el patrón de debounce en detalle
• useEventListener — enlace de evento declarativo