Blife UI

¿Qué hace?

Retrasa la ejecución de una función hasta que pase un tiempo sin nuevas llamadas. Útil para evitar ejecuciones innecesarias (como búsquedas mientras el usuario escribe).

Importación

import { useDebouncedFn } from "@blifedesarrollo/hooks";

Uso básico

Cómo funciona

const [searchTerm, setSearchTerm] = useState("");
 
// Retorna un array: [función debounced, función para cancelar]
const [debouncedSearch, cancelSearch] = useDebouncedFn((query: string) => {
  // Hacer búsqueda en API
  fetch(`/api/search?q=${query}`).then(/* ... */);
}, 400);
 
// Al escribir, se retrasa la búsqueda
const handleChange = (value: string) => {
  setSearchTerm(value);
  debouncedSearch(value); // ← Solo se ejecuta si no hay más cambios en 400ms
};

Sin debounce: Cada letra dispara una búsqueda (muchas llamadas)
Con debounce: Solo busca cuando el usuario deja de escribir (una llamada)

Opciones avanzadas

Cancelar ejecución pendiente

const [debouncedSearch, cancelSearch] = useDebouncedFn(searchFunction, 400);
 
// Cancelar si el usuario hace otra acción
const handleCancel = () => {
  cancelSearch(); // ← Cancela la búsqueda pendiente
};

API

Parámetros

Parámetro	Tipo	Descripción
`callback`	`(...args: any[]) => void`	Función a ejecutar después del retardo
`delay`	`number`	Tiempo de espera en milisegundos (opcional, default: 0)

Retorno

Retorna un array con dos valores:

const [debouncedFunction, cancel] = useDebouncedFn(callback, delay);

Elemento	Tipo	Descripción
`debouncedFunction`	`function`	Función debounced (acepta los mismos argumentos)
`cancel`	`() => void`	Cancela cualquier ejecución pendiente

Ejemplo de uso:

const [debouncedSearch, cancelSearch] = useDebouncedFn((query) => {
  // hacer búsqueda
}, 400);
 
// Usar la función
debouncedSearch("texto");
 
// Cancelar si es necesario
cancelSearch();

💡 Casos de uso comunes

Búsquedas en tiempo real → Evita llamadas a API mientras el usuario escribe
Eventos frecuentes → resize, scroll, mousemove
Guardado automático → Guarda borradores después de que el usuario deje de escribir
Validación de formularios → Valida después de que el usuario termine de escribir

use-debounced-fn