Home / Frontend / Campo de búsqueda reutilizable en React con sugerencias y debounce
Campo de búsqueda reutilizable en React con sugerencias y debounce

Campo de búsqueda reutilizable en React con sugerencias y debounce

19 November 2026 · 25 min de lectura ··

Por qué merece la pena construir un campo de sugerencias propio

Casi todas las aplicaciones web acaban necesitando un campo de texto que proponga resultados mientras el usuario escribe. Puede ser un buscador de herramientas dentro de un panel interno, un selector de etiquetas para un editor, un filtro de clientes en un CRM o un cuadro para escoger un repositorio. En cada caso la mecánica es parecida: el usuario teclea, la aplicación consulta alguna fuente de datos, aparece una lista de coincidencias y, al elegir una, el valor queda fijado en el formulario.

El problema aparece cuando esa mecánica se copia y se pega en cinco pantallas distintas. Cada copia evoluciona por su cuenta, una arregla un fallo de foco, otra añade un indicador de carga y una tercera se olvida de limpiar un listener. Un componente verdaderamente reutilizable evita esa deriva: concentra el comportamiento en un único lugar y expone una interfaz pequeña para que cada pantalla decida solo lo que le es propio, como la fuente de datos, el texto de las etiquetas o lo que ocurre al elegir un elemento.

En este tutorial construiremos desde cero un campo de entrada con sugerencias, pensado para reutilizarse. El escenario es un buscador de herramientas de desarrollo: el usuario escribe “dock” o “vite” y el componente propone coincidencias de un catálogo. Para llegar ahí resolveremos tres piezas independientes. La primera es un hook que retrasa la consulta hasta que el usuario hace una pausa al teclear. La segunda es un hook que detecta pulsaciones fuera del componente para cerrar la lista. La tercera es el propio componente, que combina ambas y añade navegación con teclado y atributos de accesibilidad.

Trabajaremos con las herramientas vigentes. La versión estable actual de React es la rama 19.3, y el proyecto lo crearemos con Vite 8, que exige Node.js 20.19 o superior, o bien 22.12 o superior. Para la red usaremos fetch nativo con AbortController, sin librerías externas de utilidades: el debounce lo escribiremos nosotros en pocas líneas.

Qué piezas componen la solución

Antes de escribir código conviene decidir el reparto de responsabilidades. Una de las ideas más útiles al diseñar componentes reutilizables es separar lo que cambia de lo que no cambia. Lo que no cambia es el comportamiento: esperar un instante, consultar, mostrar, cerrar al hacer clic fuera, navegar con flechas. Lo que sí cambia es de dónde salen los datos y cómo se pinta cada opción.

Dividiremos el trabajo en cinco archivos pequeños.

  • Un servicio con la función que busca herramientas en el catálogo.
  • El hook useDebouncedValue, que devuelve una versión retrasada de cualquier valor.
  • El hook useClickOutside, que devuelve una referencia y avisa cuando se pulsa fuera de ella.
  • El hook useSuggestions, que une el debounce con la petición y devuelve estado de carga, error y resultados.
  • El componente SearchInput, que es lo único que consumirán las pantallas.

Esta separación tiene una ventaja práctica: cada hook se puede probar y reutilizar sin el componente. El hook de debounce sirve igual para validar un formulario o guardar un borrador automáticamente, y el de clic exterior sirve para menús, modales y paneles desplegables. Si quieres profundizar en cómo organizar carpetas cuando una aplicación crece más allá de este ejemplo, te vendrá bien la guía sobre cómo estructurar proyectos React complejos.

Crear el proyecto con Vite

Vite es hoy la forma habitual de arrancar una aplicación React: el servidor de desarrollo arranca casi al instante y la compilación de producción es rápida. Comprueba primero tu versión de Node, porque Vite 8 no funciona con versiones anteriores a las indicadas.

node --version

Si el resultado es 20.19 o superior, genera el proyecto con la plantilla de React. En este ejemplo usaremos JavaScript para mantener el código corto, aunque todo lo que veremos se traslada a TypeScript añadiendo tipos a las props y a los resultados.

npm create vite@latest buscador-herramientas -- --template react
cd buscador-herramientas
npm install
npm run dev

El último comando levanta el servidor de desarrollo. La salida será parecida a esta, con el puerto por defecto de Vite.

  VITE v8.0.0  ready in 310 ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose

Comprueba además qué versión de React instaló la plantilla. Debe ser la rama 19, y por tanto podremos usar sus novedades, como pasar ref directamente como prop en componentes de función sin envolverlos con forwardRef.

npm ls react react-dom

La estructura que dejaremos al terminar es esta.

buscador-herramientas/
├── public/
│   └── herramientas.json
├── src/
│   ├── components/
│   │   ├── SearchInput.jsx
│   │   └── SearchInput.css
│   ├── hooks/
│   │   ├── useClickOutside.js
│   │   ├── useDebouncedValue.js
│   │   └── useSuggestions.js
│   ├── services/
│   │   └── herramientas.js
│   ├── App.jsx
│   └── main.jsx
├── index.html
├── package.json
└── vite.config.js

Elimina el contenido de ejemplo de App.jsx y de la hoja de estilos principal; lo sustituiremos enseguida. Todo lo que está dentro de la carpeta public se sirve tal cual desde la raíz del servidor, lo que nos permite simular una API con un simple archivo JSON.

Un catálogo de datos para simular el servidor

Para no depender de un servicio externo, guardaremos el catálogo en un archivo estático. Más adelante veremos cómo cambiarlo por una API real sin tocar el componente, que es justamente la gracia de la reutilización.

Crea public/herramientas.json con unos cuantos registros. Añade los que quieras; cuantos más haya, mejor se apreciará el filtrado.

[
  { "id": 1, "nombre": "Docker", "categoria": "Contenedores" },
  { "id": 2, "nombre": "Docker Compose", "categoria": "Contenedores" },
  { "id": 3, "nombre": "Vite", "categoria": "Compilación" },
  { "id": 4, "nombre": "Vitest", "categoria": "Pruebas" },
  { "id": 5, "nombre": "ESLint", "categoria": "Calidad" },
  { "id": 6, "nombre": "Prettier", "categoria": "Calidad" },
  { "id": 7, "nombre": "Playwright", "categoria": "Pruebas" },
  { "id": 8, "nombre": "PostgreSQL", "categoria": "Bases de datos" },
  { "id": 9, "nombre": "Redis", "categoria": "Bases de datos" },
  { "id": 10, "nombre": "Git", "categoria": "Control de versiones" },
  { "id": 11, "nombre": "GitHub Actions", "categoria": "Integración continua" },
  { "id": 12, "nombre": "Terraform", "categoria": "Infraestructura" }
]

Ahora el servicio que consulta ese catálogo. Su firma es la que el resto del sistema esperará: recibe el texto buscado y una señal de cancelación, y devuelve una promesa con un arreglo de resultados.

// src/services/herramientas.js
let catalogo = null;

async function cargarCatalogo(signal) {
  if (catalogo) return catalogo;

  const respuesta = await fetch("/herramientas.json", { signal });
  if (!respuesta.ok) {
    throw new Error(`No se pudo cargar el catálogo (${respuesta.status})`);
  }

  catalogo = await respuesta.json();
  return catalogo;
}

function normalizar(texto) {
  return texto
    .toLowerCase()
    .normalize("NFD")
    .replace(/[̀-ͯ]/g, "");
}

export async function buscarHerramientas(texto, signal) {
  const datos = await cargarCatalogo(signal);
  const buscado = normalizar(texto);

  return datos.filter((item) => normalizar(item.nombre).includes(buscado));
}

Hay dos detalles que merecen atención. El primero es que el catálogo se guarda en una variable de módulo: como los datos son estáticos, descargarlos en cada pulsación sería un desperdicio. El segundo es la función normalizar, que descompone los caracteres acentuados y elimina las marcas, de forma que buscar “base” encuentre “Bases de datos” y que las mayúsculas no importen. Ese cuidado con los acentos es especialmente importante en interfaces en español.

Retrasar la consulta con un hook de debounce

Si lanzáramos una consulta por cada tecla, escribir la palabra “terraform” dispararía nueve peticiones, de las cuales ocho serían inútiles. El debounce resuelve esto: en lugar de reaccionar a cada cambio, espera a que pase un intervalo sin novedades y solo entonces actúa.

Hay dos formas de implementarlo en React. Una es retrasar la función que hace la consulta, y la otra es retrasar el valor. Optaremos por la segunda, porque encaja mejor con el modelo declarativo: el componente guarda lo que el usuario escribe al instante, y el hook ofrece una copia que se actualiza con retraso. Todo lo que dependa de la copia retrasada se recalcula solo cuando el usuario hace una pausa.

// src/hooks/useDebouncedValue.js
import { useEffect, useState } from "react";

export function useDebouncedValue(value, delay = 300) {
  const [debounced, setDebounced] = useState(value);

  useEffect(() => {
    const temporizador = setTimeout(() => setDebounced(value), delay);
    return () => clearTimeout(temporizador);
  }, [value, delay]);

  return debounced;
}

La clave está en la función de limpieza. Cada vez que value cambia, React ejecuta primero la limpieza del efecto anterior, que cancela el temporizador pendiente, y después programa uno nuevo. Si el usuario escribe más rápido que el intervalo, los temporizadores se van cancelando uno tras otro y solo sobrevive el último. Aquí no necesitamos guardar nada en una referencia mutable, porque el propio temporizador vive dentro del cierre del efecto y se cancela en su limpieza.

Un intervalo de 250 a 400 milisegundos suele ser un buen punto de partida. Por debajo de 200 apenas reduces peticiones, y por encima de 500 la interfaz empieza a sentirse perezosa. Como el valor se pasa por parámetro, cada pantalla puede ajustarlo según el coste de su fuente de datos.

Detectar clics fuera del componente

Una lista desplegable que no se cierra al pulsar en otra parte de la página resulta molesta. Para resolverlo necesitamos escuchar eventos a nivel de documento y comprobar si el destino del evento queda dentro o fuera de nuestro contenedor.

El hook devolverá una referencia que el componente asignará a su elemento raíz, y recibirá una función que se ejecutará cuando se detecte una pulsación exterior.

// src/hooks/useClickOutside.js
import { useEffect, useRef } from "react";

export function useClickOutside(onOutside) {
  const ref = useRef(null);
  const callbackRef = useRef(onOutside);

  useEffect(() => {
    callbackRef.current = onOutside;
  });

  useEffect(() => {
    function manejar(evento) {
      if (ref.current && !ref.current.contains(evento.target)) {
        callbackRef.current(evento);
      }
    }

    document.addEventListener("pointerdown", manejar);
    return () => document.removeEventListener("pointerdown", manejar);
  }, []);

  return ref;
}

Hay varias decisiones aquí que conviene explicar, porque son las que separan una versión frágil de una robusta.

La primera es usar pointerdown en lugar de click. El evento de puntero se dispara al presionar, tanto con ratón como con pantalla táctil o lápiz, y evita ciertos casos raros en los que un click llega después de que el elemento sobre el que se pulsó haya desaparecido del árbol de nodos, lo que haría que contains devolviera un falso negativo.

La segunda es guardar la función recibida en una referencia. Si el listener dependiera directamente de onOutside, habría que volver a registrarlo cada vez que el componente padre pasara una función nueva, algo que ocurre en cada renderizado cuando se escribe una flecha en línea. Con la referencia, el listener se registra una única vez y siempre invoca la versión más reciente de la función. Este patrón es habitual cuando un efecto debe ser estable pero necesita datos frescos.

La tercera es la limpieza: quitar el listener al desmontar evita fugas de memoria y llamadas a componentes que ya no existen. Con el modo estricto de desarrollo, React monta, desmonta y vuelve a montar cada componente para ayudarte a detectar justamente este tipo de descuido, así que si olvidaras la limpieza lo notarías al instante.

Un hook que une la espera, la red y la cancelación

Con el debounce listo, falta el hook que lanza la consulta. Su trabajo es observar el texto retrasado, pedir resultados a la función de búsqueda que le pasemos y reflejar en un estado si estamos cargando, si hubo un error o si ya hay datos.

// src/hooks/useSuggestions.js
import { useEffect, useState } from "react";
import { useDebouncedValue } from "./useDebouncedValue";

const ESTADO_INICIAL = { items: [], status: "idle", error: null };

export function useSuggestions(buscar, texto, { minChars = 2, delay = 300 } = {}) {
  const consulta = useDebouncedValue(texto.trim(), delay);
  const [estado, setEstado] = useState(ESTADO_INICIAL);

  useEffect(() => {
    if (consulta.length < minChars) {
      setEstado(ESTADO_INICIAL);
      return;
    }

    const controlador = new AbortController();
    setEstado((previo) => ({ ...previo, status: "loading", error: null }));

    buscar(consulta, controlador.signal)
      .then((items) => setEstado({ items, status: "done", error: null }))
      .catch((error) => {
        if (error.name === "AbortError") return;
        setEstado({ items: [], status: "error", error: error.message });
      });

    return () => controlador.abort();
  }, [consulta, minChars, buscar]);

  return estado;
}

El AbortController es lo que convierte este hook en algo fiable. Imagina que el usuario escribe “doc”, espera, y la petición tarda dos segundos en una red lenta; mientras tanto escribe “docker” y la segunda respuesta llega antes que la primera. Sin cancelación, la respuesta antigua podría llegar más tarde y sobrescribir la nueva, mostrando sugerencias que ya no corresponden a lo escrito. Al abortar la petición en la función de limpieza del efecto, la anterior se descarta y su promesa se rechaza con un error de tipo AbortError, que simplemente ignoramos.

Un matiz: el estado inicial es un objeto definido fuera del hook. Así, al volver a establecerlo, React compara por referencia y evita un renderizado innecesario cuando el estado ya era el inicial.

El segundo matiz es la dependencia buscar. Si el componente padre pasara una función definida dentro de su cuerpo, cambiaría en cada renderizado y el efecto se reejecutaría sin parar. Por eso nuestro servicio exporta una función de módulo, que es estable por naturaleza. Cuando necesites una función que dependa de props, envuélvela con useCallback antes de entregarla al componente. Si estos conceptos de funciones y props te resultan nuevos, repasa los fundamentos esenciales de React sobre funciones, props y JSX.

El componente reutilizable paso a paso

Llegamos a la pieza central. Un componente reutilizable debe aceptar por props todo lo que varía entre usos y encargarse él mismo de lo que no varía. Estas son las props que definiremos.

  • label: el texto visible de la etiqueta.
  • name: el nombre del campo, útil si se integra en un formulario.
  • placeholder: el texto de ayuda dentro del campo.
  • buscar: la función que consulta los datos, con firma de texto y señal.
  • obtenerTexto: cómo obtener el texto que se muestra de cada resultado.
  • onSelect: la función que se ejecuta al elegir una sugerencia.
  • minChars y delay: parámetros opcionales de comportamiento.

Con eso, el componente queda así. Lo veremos primero completo y luego lo diseccionaremos.

// src/components/SearchInput.jsx
import { useId, useState } from "react";
import { useClickOutside } from "../hooks/useClickOutside";
import { useSuggestions } from "../hooks/useSuggestions";
import "./SearchInput.css";

export default function SearchInput({
  label,
  name,
  placeholder = "Escribe para buscar",
  buscar,
  obtenerTexto = (item) => item.nombre,
  onSelect,
  minChars = 2,
  delay = 300,
}) {
  const idBase = useId();
  const idLista = `${idBase}-lista`;

  const [texto, setTexto] = useState("");
  const [abierto, setAbierto] = useState(false);
  const [activo, setActivo] = useState(-1);

  const contenedor = useClickOutside(() => setAbierto(false));
  const { items, status, error } = useSuggestions(buscar, texto, { minChars, delay });

  const hayLista = abierto && items.length > 0;

  function elegir(item) {
    setTexto(obtenerTexto(item));
    setAbierto(false);
    setActivo(-1);
    onSelect?.(item);
  }

  function alEscribir(evento) {
    setTexto(evento.target.value);
    setAbierto(true);
    setActivo(-1);
  }

  return (
    <div className="search-input" ref={contenedor}>
      <label htmlFor={`${idBase}-campo`}>{label}</label>

      <input
        id={`${idBase}-campo`}
        name={name}
        type="text"
        role="combobox"
        autoComplete="off"
        placeholder={placeholder}
        value={texto}
        onChange={alEscribir}
        onFocus={() => setAbierto(true)}
        aria-expanded={hayLista}
        aria-controls={idLista}
        aria-autocomplete="list"
        aria-activedescendant={activo >= 0 ? `${idBase}-op-${activo}` : undefined}
      />

      {status === "loading" && <p className="search-input__estado">Buscando...</p>}
      {status === "error" && (
        <p className="search-input__estado search-input__estado--error" role="alert">
          {error}
        </p>
      )}
      {status === "done" && items.length === 0 && abierto && (
        <p className="search-input__estado">Sin coincidencias</p>
      )}

      {hayLista && (
        <ul id={idLista} role="listbox" className="search-input__lista">
          {items.map((item, indice) => (
            <li
              key={item.id}
              id={`${idBase}-op-${indice}`}
              role="option"
              aria-selected={indice === activo}
              className={indice === activo ? "activa" : undefined}
              onPointerDown={(e) => e.preventDefault()}
              onClick={() => elegir(item)}
            >
              {obtenerTexto(item)}
            </li>
          ))}
        </ul>
      )}
    </div>
  );
}

Repasemos las decisiones. El estado se reparte en tres variables con propósitos distintos: texto es lo que hay escrito, abierto controla si la lista es visible y activo guarda qué opción está resaltada con el teclado. Los resultados, la carga y el error no se guardan aquí porque ya los gestiona el hook de sugerencias.

El texto que aparece en cada opción se obtiene con obtenerTexto, que por defecto lee la propiedad nombre. Gracias a ello, el mismo componente puede mostrar usuarios, repositorios o productos con solo pasar otra función. Esa es la forma más sencilla de lograr un componente verdaderamente genérico sin complicar su interfaz.

Una pequeña sutileza es el onPointerDown con preventDefault en cada opción: evita que el campo pierda el foco al pulsar sobre una sugerencia, lo que produciría parpadeos en la lista antes de registrarse el clic.

También usamos useId, que genera identificadores únicos y estables. Esto es imprescindible en un componente reutilizable: si el mismo componente se pinta dos veces en la página, los identificadores fijos como “lista” colisionarían y romperían la asociación entre etiqueta y campo, y los atributos de accesibilidad apuntarían al elemento equivocado.

Estilos mínimos para la lista

El comportamiento es independiente del aspecto, pero un desplegable necesita posicionamiento. El contenedor raíz será el punto de referencia y la lista se colocará justo debajo del campo.

/* src/components/SearchInput.css */
.search-input {
  position: relative;
  max-width: 360px;
  margin-bottom: 1.5rem;
}

.search-input label {
  display: block;
  margin-bottom: 0.25rem;
  font-weight: 600;
}

.search-input input {
  width: 100%;
  padding: 0.55rem 0.75rem;
  border: 1px solid #94a3b8;
  border-radius: 6px;
  font-size: 1rem;
  box-sizing: border-box;
}

.search-input__lista {
  position: absolute;
  top: 100%;
  left: 0;
  right: 0;
  z-index: 10;
  margin: 4px 0 0;
  padding: 0;
  list-style: none;
  background: #ffffff;
  border: 1px solid #cbd5e1;
  border-radius: 6px;
  max-height: 220px;
  overflow-y: auto;
  box-shadow: 0 6px 16px rgba(15, 23, 42, 0.12);
}

.search-input__lista li {
  padding: 0.5rem 0.75rem;
  cursor: pointer;
}

.search-input__lista li:hover,
.search-input__lista li.activa {
  background: #e0f2fe;
}

.search-input__estado {
  margin: 0.35rem 0 0;
  font-size: 0.9rem;
  color: #475569;
}

.search-input__estado--error {
  color: #b91c1c;
}

Fíjate en el max-height con overflow-y: auto: si el servidor devuelve cincuenta coincidencias, la lista no se desborda por toda la página. En un caso real conviene además limitar el número de resultados en el origen. Cuando las coincidencias son muy numerosas y el usuario necesita explorarlas todas, un patrón complementario es ofrecer una carga progresiva; puedes ver cómo hacerlo en el artículo sobre paginación incremental con un botón de cargar más y hooks.

Reutilizarlo en la aplicación con dos instancias

La prueba de fuego de la reutilización es usar el componente más de una vez con configuraciones distintas. En App.jsx pintaremos dos campos: uno para buscar la herramienta principal del proyecto y otro para elegir una herramienta de apoyo, con su propio texto y su propio manejador.

// src/App.jsx
import { useState } from "react";
import SearchInput from "./components/SearchInput";
import { buscarHerramientas } from "./services/herramientas";

export default function App() {
  const [principal, setPrincipal] = useState(null);
  const [apoyo, setApoyo] = useState(null);

  return (
    <main style={{ padding: "2rem", fontFamily: "system-ui, sans-serif" }}>
      <h1>Pila tecnológica del proyecto</h1>

      <SearchInput
        label="Herramienta principal"
        name="principal"
        placeholder="Por ejemplo, Vite"
        buscar={buscarHerramientas}
        onSelect={setPrincipal}
      />

      <SearchInput
        label="Herramienta de apoyo"
        name="apoyo"
        placeholder="Por ejemplo, Docker"
        buscar={buscarHerramientas}
        obtenerTexto={(item) => `${item.nombre} (${item.categoria})`}
        minChars={1}
        delay={200}
        onSelect={setApoyo}
      />

      <p>Principal: {principal ? principal.nombre : "sin elegir"}</p>
      <p>Apoyo: {apoyo ? apoyo.nombre : "sin elegir"}</p>
    </main>
  );
}

Cada instancia mantiene su propio texto, su propia lista y su propio estado de apertura, porque el estado vive dentro del componente y no se comparte. Abre las dos, despliega la lista de una y haz clic en el otro campo: la primera se cierra gracias al hook de clic exterior, y la segunda se abre sin interferencias.

El segundo campo demuestra la flexibilidad del diseño. Usa un umbral de un solo carácter, un retraso menor y una función distinta para mostrar el texto, y todo ello sin modificar una sola línea del componente.

Un campo de sugerencias que solo funciona con ratón excluye a muchas personas, y también a quienes simplemente prefieren no soltar el teclado. El patrón recomendado para esto es el de combinación de campo y lista, conocido como combobox. Ya añadimos los atributos principales: el rol combobox en el campo, el rol listbox en la lista, el rol option en cada elemento y aria-activedescendant para indicar a los lectores de pantalla qué opción está resaltada sin mover el foco del campo.

Falta el comportamiento de teclado. Añadimos un manejador onKeyDown al campo que cubra las flechas, Enter y Escape.

function alPulsarTecla(evento) {
  if (!hayLista) {
    if (evento.key === "ArrowDown") setAbierto(true);
    return;
  }

  switch (evento.key) {
    case "ArrowDown":
      evento.preventDefault();
      setActivo((previo) => (previo + 1) % items.length);
      break;
    case "ArrowUp":
      evento.preventDefault();
      setActivo((previo) => (previo <= 0 ? items.length - 1 : previo - 1));
      break;
    case "Enter":
      if (activo >= 0) {
        evento.preventDefault();
        elegir(items[activo]);
      }
      break;
    case "Escape":
      setAbierto(false);
      setActivo(-1);
      break;
    default:
      break;
  }
}

Para activarlo, añade onKeyDown={alPulsarTecla} al elemento input. Observa que preventDefault en las flechas evita que el cursor salte al principio o al final del texto, y que en Enter solo lo usamos cuando hay una opción activa, de modo que el formulario siga pudiendo enviarse si el usuario no eligió nada.

Hay otros dos refinamientos que merece la pena aplicar. El primero es que la opción activa debe quedar visible cuando la lista tiene scroll; se consigue con una referencia a ese elemento y una llamada a scrollIntoView con la opción block: "nearest" en un efecto que dependa del índice activo. El segundo es avisar de los cambios dinámicos a los lectores de pantalla: un párrafo con aria-live="polite" que diga, por ejemplo, “5 resultados disponibles” permite que quien no ve la lista sepa que ha aparecido.

Por último, comprueba el contraste de colores de la opción resaltada y no dependas solo del color para señalarla. Un borde o un cambio de peso tipográfico añade una pista visual adicional que ayuda a personas con daltonismo.

Condiciones de carrera y errores de red

Ya mencionamos que la cancelación evita que una respuesta lenta pise a una rápida. Vale la pena detenerse a verificarlo, porque es el tipo de fallo que no aparece en desarrollo con una red local y sí en producción.

Para forzar el problema, puedes simular latencia en tu función de búsqueda añadiendo una espera aleatoria antes de devolver los resultados.

const esperar = (ms, signal) =>
  new Promise((resolver, rechazar) => {
    const id = setTimeout(resolver, ms);
    signal?.addEventListener("abort", () => {
      clearTimeout(id);
      rechazar(new DOMException("Cancelado", "AbortError"));
    });
  });

export async function buscarConRetraso(texto, signal) {
  await esperar(Math.random() * 1500, signal);
  return buscarHerramientas(texto, signal);
}

Cambia temporalmente buscar={buscarHerramientas} por buscar={buscarConRetraso}, escribe y borra con rapidez y observa que la lista siempre se corresponde con el último texto. Si quitaras la llamada a abort del hook, verías cómo a veces las sugerencias no coinciden con lo escrito.

En cuanto a los errores, hay que distinguir entre fallos de red, respuestas con código de error y datos mal formados. Nuestro servicio ya convierte una respuesta no satisfactoria en una excepción con mensaje legible, y el hook la refleja en el estado. En el componente, el mensaje de error usa el rol alert para que se anuncie automáticamente. Una mejora razonable es ofrecer un botón de reintento o conservar los últimos resultados correctos mientras se muestra el aviso, según lo que espere tu producto.

Cuando migres a una API real, el cambio se limita a la función de búsqueda. El componente no se entera de si los datos vienen de un archivo, de una base de datos o de un motor de búsqueda.

// src/services/herramientasApi.js
export async function buscarEnApi(texto, signal) {
  const parametros = new URLSearchParams({ q: texto, limite: "8" });
  const respuesta = await fetch(`/api/herramientas?${parametros}`, { signal });

  if (!respuesta.ok) {
    throw new Error(`Error del servidor (${respuesta.status})`);
  }

  return respuesta.json();
}

El uso de URLSearchParams garantiza que el texto del usuario se codifique correctamente, evitando que un carácter como el ampersand rompa la consulta. En el servidor, recuerda limitar la longitud de la consulta y el número de resultados, y aplicar límites de peticiones, porque un campo con sugerencias genera mucho más tráfico que un formulario normal.

Errores frecuentes y cómo evitarlos

Aunque el diseño sea correcto, hay trampas habituales al implementar este tipo de componentes. Estas son las que más se repiten.

  • Olvidar la limpieza de listeners o temporizadores. Cada addEventListener o setTimeout en un efecto necesita su contrapartida en la función devuelta.
  • Pasar a un hook una función definida en línea y colocarla en las dependencias de un efecto, lo que provoca consultas infinitas. Estabilízala con useCallback o muévela fuera del componente.
  • Usar índices del arreglo como clave de las opciones. Si el orden cambia entre consultas, React puede reutilizar nodos del DOM de forma incorrecta. Emplea siempre un identificador propio del dato.
  • Consultar con el texto sin recortar. Un espacio al final genera una consulta distinta y una petición extra; por eso aplicamos trim antes del debounce.
  • Mostrar “sin resultados” mientras todavía se espera la respuesta. Distingue el estado de carga del estado vacío, como hicimos con la propiedad status.
  • Dejar abierta la lista tras elegir. Cierra y reinicia el índice activo en cuanto el usuario confirma una opción.
  • Ignorar el comportamiento en pantallas táctiles. Usar eventos de puntero en lugar de eventos de ratón cubre ambos mundos con el mismo código.

Otro error sutil es confundir el valor mostrado con el valor seleccionado. En nuestro ejemplo, el campo guarda el texto, pero lo que la aplicación necesita es el objeto elegido, que entrega onSelect. Si en un formulario real necesitas enviar un identificador, añade un campo oculto o guarda el elemento elegido en el estado del formulario, y limpia esa selección cuando el usuario vuelva a editar el texto, para no enviar un dato que ya no coincide con lo escrito.

Rendimiento y pruebas

El rendimiento de este componente depende sobre todo de cuántas consultas se lanzan y de cuánto cuesta cada una. El debounce y la cancelación ya reducen el trabajo de red; el resto es cuestión de medir.

Si tu catálogo es grande y se filtra en el navegador, normalizar todos los nombres en cada consulta puede ser caro. Una mejora sencilla es precalcular el texto normalizado una sola vez al cargar los datos y guardarlo junto a cada registro, de modo que el filtrado solo compare cadenas ya preparadas. Para decenas de miles de registros, plantéate mover la búsqueda a un servidor o a un trabajador web.

Respecto a React, el componente no necesita memo ni optimizaciones manuales en un uso normal, porque los renderizados ocurren al escribir y la lista es corta. Si pintas centenares de opciones, limita el número de resultados o recurre a virtualización de listas. Antes de optimizar, usa el panel de rendimiento de las herramientas de desarrollo del navegador y confirma que existe un problema real.

Para las pruebas, los hooks pequeños son fáciles de verificar. Con Vitest, que se integra de forma natural con Vite, puedes usar temporizadores simulados para comprobar que el valor retrasado no cambia hasta que pasa el intervalo.

npm install -D vitest @testing-library/react @testing-library/user-event jsdom

Un caso de prueba típico para el hook de debounce sería el siguiente.

// src/hooks/useDebouncedValue.test.js
import { renderHook, act } from "@testing-library/react";
import { describe, it, expect, vi } from "vitest";
import { useDebouncedValue } from "./useDebouncedValue";

describe("useDebouncedValue", () => {
  it("espera el intervalo antes de actualizar", () => {
    vi.useFakeTimers();
    const { result, rerender } = renderHook(
      ({ valor }) => useDebouncedValue(valor, 300),
      { initialProps: { valor: "a" } }
    );

    rerender({ valor: "ab" });
    expect(result.current).toBe("a");

    act(() => vi.advanceTimersByTime(300));
    expect(result.current).toBe("ab");

    vi.useRealTimers();
  });
});

Para el componente completo, las pruebas más valiosas son de comportamiento: escribir, esperar a que aparezcan opciones, navegar con flechas, pulsar Enter y comprobar que onSelect se llamó con el objeto correcto. Sustituye la función de búsqueda por una versión falsa que devuelva datos fijos, y tendrás pruebas rápidas y deterministas, que es otra ventaja de recibir la fuente de datos por props.

Alternativas y cuándo conviene usarlas

Construir el componente a mano tiene sentido cuando necesitas control total, una dependencia mínima o una interfaz muy particular. Pero no siempre es la mejor opción.

Existen librerías de componentes sin estilos, centradas en accesibilidad, que ofrecen un combobox completo con gestión de foco, teclado y lectores de pantalla ya resuelta. Son una buena elección cuando tu equipo no quiere mantener esos detalles. Otras bibliotecas más pesadas incluyen selectores con múltiples valores, creación de opciones al vuelo y carga asíncrona, útiles para formularios complejos.

Para el debounce, si ya utilizas una librería de utilidades, su función de retraso es válida, pero hay que crearla una sola vez por componente y no en cada renderizado. Nuestra versión basada en un hook de valor evita ese riesgo y no añade peso. Si la consulta es una petición de datos, también puedes apoyarte en una librería de gestión de datos de servidor, que aporta caché, reintentos y deduplicación; en ese caso el hook de debounce se mantiene y la librería sustituye a la parte de estado y cancelación.

El elemento nativo de datalist ofrece sugerencias sin una línea de JavaScript, pero su aspecto y comportamiento varían entre navegadores y no permite personalizar la lista ni mostrar estados de carga. Sirve para casos sencillos con listas cortas y estáticas; para cualquier cosa más ambiciosa, un componente propio compensa.

La decisión depende del equilibrio entre control y mantenimiento. Para una aplicación pequeña o un aprendizaje, el enfoque artesanal es excelente. Para un producto con requisitos estrictos de accesibilidad en muchos idiomas y dispositivos, apoyarse en una pieza ya probada reduce el riesgo.

Ideas para seguir mejorando el componente

Una vez que lo básico funciona, hay varias extensiones que aportan valor sin cambiar el diseño.

  • Resaltar en cada opción la parte que coincide con lo escrito, dividiendo el texto en fragmentos.
  • Recordar las últimas selecciones del usuario y mostrarlas al enfocar el campo vacío.
  • Soportar selección múltiple, mostrando los elementos elegidos como fichas dentro del contenedor.
  • Permitir pasar una función para pintar cada opción, de modo que se puedan incluir iconos o descripciones.
  • Convertir el componente en controlado, aceptando un valor y una función de cambio desde el exterior para integrarlo con librerías de formularios.
  • Añadir tipado con TypeScript y genéricos, de forma que buscar, obtenerTexto y onSelect compartan el mismo tipo de elemento y el compilador detecte incoherencias.

Cada una de estas ampliaciones es un buen ejercicio, y casi todas se resuelven añadiendo una prop opcional con un valor por defecto razonable, manteniendo la compatibilidad con los usos anteriores. Esa disciplina de no romper a quien ya usa el componente es lo que lo mantiene realmente reutilizable con el paso del tiempo.

Conclusiones

Hemos construido un campo de búsqueda con sugerencias que se puede colocar en cualquier pantalla con pocas líneas. La clave no ha sido el código aislado, sino la forma de repartirlo: un hook para esperar, otro para detectar clics externos, un tercero para consultar y cancelar, y un componente que los ensambla y se limita a recibir por props lo que cambia.

El primer aprendizaje es que el debounce basado en valores resulta más natural en React que retrasar funciones, porque se apoya en el ciclo de vida de los efectos y en su limpieza, y no requiere referencias mutables. El segundo es que la cancelación de peticiones obsoletas es tan importante como el retraso, ya que evita que una respuesta lenta sobrescriba una más reciente. El tercero es que un componente de uso general debe nacer con identificadores únicos, teclado y atributos de accesibilidad, porque añadirlos después suele costar más.

También hemos visto cómo las herramientas actuales simplifican el trabajo: Vite 8 arranca el proyecto en segundos, React 19 permite pasar referencias como props sin envolturas, y fetch con AbortController cubre la red sin dependencias adicionales. Con ese terreno firme, tu siguiente paso puede ser sustituir el catálogo estático por una API real, probar el comportamiento con Vitest y adaptar el componente a los casos de tu propio proyecto.