useDebounce — Retrasa actualizaciones de valores o ejecución de callbacks hasta que la entrada se estabilice

Receta

Dos hooks complementarios: useDebouncedValue retrasa un valor reactivo; useDebouncedCallback retrasa una llamada de función.

import { useState, useEffect, useRef, useCallback, useMemo } from "react";
 
/**
 * useDebouncedValue
 * Devuelve una copia retrasada de `value` que solo se actualiza
 * después de `delay` ms de inactividad.
 */
function useDebouncedValue<T>(value: T, delay: number): T {
  const [debounced, setDebounced] = useState(value);
 
  useEffect(() => {
    const id = setTimeout(() => setDebounced(value), delay);
    return () => clearTimeout(id);
  }, [value, delay]);
 
  return debounced;
}
 
/**
 * useDebouncedCallback
 * Devuelve una versión estable retrasada de `callback`.
 * Soporta invocación en el borde inicial a través de `options.leading`.
 */
function useDebouncedCallback<T extends (...args: any[]) => void>(
  callback: T,
  delay: number,
  options: { leading?: boolean } = {}
): T & { cancel: () => void; flush: () => void } {
  const { leading = false } = options;
  const callbackRef = useRef(callback);
  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
  const lastArgsRef = useRef<Parameters<T> | null>(null);
  const leadingFiredRef = useRef(false);
 
  // Siempre mantener el callback más reciente
  useEffect(() => {
    callbackRef.current = callback;
  }, [callback]);
 
  // Limpieza al desmontar
  useEffect(() => {
    return () => {
      if (timerRef.current) clearTimeout(timerRef.current);
    };
  }, []);
 
  const cancel = useCallback(() => {
    if (timerRef.current) clearTimeout(timerRef.current);
    timerRef.current = null;
    lastArgsRef.current = null;
    leadingFiredRef.current = false;
  }, []);
 
  const flush = useCallback(() => {
    if (lastArgsRef.current) {
      callbackRef.current(...lastArgsRef.current);
    }
    cancel();
  }, [cancel]);
 
  const debounced = useCallback(
    (...args: Parameters<T>) => {
      lastArgsRef.current = args;
 
      if (leading && !leadingFiredRef.current) {
        leadingFiredRef.current = true;
        callbackRef.current(...args);
      }
 
      if (timerRef.current) clearTimeout(timerRef.current);
 
      timerRef.current = setTimeout(() => {
        if (!leading) {
          callbackRef.current(...args);
        }
        leadingFiredRef.current = false;
        timerRef.current = null;
        lastArgsRef.current = null;
      }, delay);
    },
    [delay, leading]
  ) as T & { cancel: () => void; flush: () => void };
 
  debounced.cancel = cancel;
  debounced.flush = flush;
 
  return debounced;
}

Cuándo usarlo: Necesitas evitar hacer demasiadas solicitudes a una API en cada pulsación de tecla (búsqueda mientras escribes), o quieres agrupar eventos rápidos como resize o scroll en una única actualización.

Ejemplo Funcionando

"use client";
 
import { useState } from "react";
 
function SearchInput() {
  const [query, setQuery] = useState("");
  const debouncedQuery = useDebouncedValue(query, 300);
 
  // Solo dispara solicitud de red cuando debouncedQuery cambia
  useEffect(() => {
    if (!debouncedQuery) return;
    fetch(`/api/search?q=${encodeURIComponent(debouncedQuery)}`)
      .then((res) => res.json())
      .then((data) => console.log(data));
  }, [debouncedQuery]);
 
  return (
    <input
      value={query}
      onChange={(e) => setQuery(e.target.value)}
      placeholder="Buscar..."
    />
  );
}
 
function SaveButton() {
  const debouncedSave = useDebouncedCallback(
    (content: string) => {
      fetch("/api/save", {
        method: "POST",
        body: JSON.stringify({ content }),
      });
    },
    1000,
    { leading: true }
  );
 
  return (
    <button onClick={() => debouncedSave("draft content")}>
      Guardar (retrasado)
    </button>
  );
}

Lo que demuestra esto:

• useDebouncedValue retrasa la consulta de búsqueda para que la API se llame solo después de que el usuario deje de escribir durante 300 ms
• useDebouncedCallback con leading: true dispara inmediatamente al primer clic, luego ignora clics rápidos durante 1 segundo
• Ambos hooks limpian automáticamente los timers al desmontar

Profundización

Cómo Funciona

• useDebouncedValue establece un setTimeout cada vez que value cambia. La función de limpieza en useEffect borra el timer anterior, por lo que solo la última actualización dentro de delay ms realmente se registra en el state.
• useDebouncedCallback almacena el callback más reciente en una ref para que los llamadores nunca necesiten preocuparse por cierres obsoletos. Una única ref de timer se reutiliza entre llamadas.
• La opción del borde inicial dispara el callback inmediatamente en la primera invocación, luego suprime llamadas posteriores hasta que el retraso transcurra sin actividad.
• cancel() borra cualquier invocación pendiente. flush() invoca el callback pendiente inmediatamente y reinicia el state.
• Ambos hooks se limpian al desmontar para prevenir advertencias de "setState on unmounted component".

Parámetros y Valores Devueltos

useDebouncedValue

useDebouncedCallback

Variaciones

Modo inmediato (leading + trailing): Dispara en ambos bordes manteniendo un registro de si la llamada trailing también debe dispararse. Útil para botones de guardar donde quieres retroalimentación instantánea más un guardado final.

// Dispara en ambos bordes inicial y final
function useDebouncedCallback(callback, delay, { leading: true, trailing: true })

Con maxWait: Garantiza que el callback se dispare al menos cada maxWait ms incluso si la entrada nunca se detiene. Combina debounce con un timer maxWait para limitar el retraso.

Notas de TypeScript

• useDebouncedValue es genérico sobre T, por lo que el tipo devuelto coincide automáticamente con el tipo de entrada.
• useDebouncedCallback preserva los tipos de parámetro del callback original a través de Parameters<T>.
• El patrón de tupla as const no es necesario aquí ya que ambos hooks devuelven valores únicos u objetos.

Trampas

• Cierre obsoleto en callback — Si incluyes el callback directamente sin el patrón de ref, las variables capturadas pueden estar obsoletas cuando el timer se dispare. Solución: El patrón de ref en useDebouncedCallback siempre llama a la versión más reciente.
• Retraso de cero — setTimeout(fn, 0) aún se difiere al siguiente tick, lo que puede causar un destello visible. Solución: Usa un guard como if (delay <= 0) return callback(...) para casos de retraso cero.
• Actualizaciones de state después de desmontar — Si el componente se desmonta antes de que el timer se dispare, React advierte sobre actualizaciones filtradas. Solución: La limpieza en useEffect maneja esto; asegúrate de no omitirla.
• Desincronización de hidratación — useDebouncedValue se inicializa con el valor sin procesar (sin setTimeout en el servidor), por lo que no hay desincronización de hidratación. No se necesita manejo especial.

Alternativas

Ejemplo del Mundo Real

De una aplicación SaaS Next.js 15 / React 19 en producción (SystemsArchitect.io).

// Ejemplo de producción: patrón debounce integrado con SWR
// Archivo: src/hooks/use-search.ts
import { useState, useEffect, useMemo } from 'react';
import useSWR from 'swr';
 
const fetcher = (url: string) => fetch(url).then((r) => r.json());
 
export function useSearch(query: string, platform: string) {
  const [debouncedQuery, setDebouncedQuery] = useState(query);
 
  // Debounce: solo actualiza la consulta después de 300ms de inactividad
  useEffect(() => {
    const timer = setTimeout(() => setDebouncedQuery(query), 300);
    return () => clearTimeout(timer);
  }, [query]);
 
  const shouldFetch = debouncedQuery.length >= 3;
  const apiUrl = shouldFetch
    ? `/api/search?q=${encodeURIComponent(debouncedQuery)}&platform=${platform}`
    : null;
 
  const { data, isLoading, isValidating } = useSWR(apiUrl, fetcher, {
    keepPreviousData: true,
  });
 
  return useMemo(() => ({
    results: data?.results ?? [],
    isLoading: isLoading || (shouldFetch && isValidating),
  }), [data, isLoading, shouldFetch, isValidating]);
}

Lo que demuestra en producción:

• El setTimeout + clearTimeout limpieza en useEffect es el mecanismo debounce central. Cada vez que query cambia, el timeout anterior se borra y uno nuevo comienza. Solo cuando el usuario deja de escribir durante 300ms setDebouncedQuery se dispara.
• Este es el patrón useDebouncedValue aplicado directamente en línea. En producción, se mantuvieron en línea en lugar de extraer a un hook separado porque el debounce está estrechamente acoplado con la lógica de fetch de SWR y la verificación de longitud mínima.
• La función de limpieza return () => clearTimeout(timer) es crítica. Sin ella, una escritura rápida programaría múltiples timeouts, y consultas obsoletas se dispararían fuera de orden. La limpieza garantiza que solo el último timeout sobreviva.
• La convención de clave null de SWR (cuando shouldFetch es falso) previene el fetch completamente. No se realiza solicitud hasta que la consulta retrasada alcanza 3 caracteres.
• keepPreviousData: true previene un destello de resultados en blanco mientras se recupera la nueva consulta retrasada. Los resultados anteriores permanecen visibles hasta que llegan datos frescos.

Preguntas Frecuentes

const debouncedSave = useDebouncedCallback(save, 1000);
// Más tarde:
debouncedSave.cancel();

const debounced = useDebouncedValue("hello", 300);
// debounced se infiere como string

Relacionado

• useThrottle — limita la velocidad en lugar de retrasar
• useFetch — combina con consultas retrasadas
• useEffect — la primitiva subyacente