Autocomplete

Campo de texto que busca en un endpoint de API o en un arreglo local mientras el usuario escribe. Los resultados aparecen en un popover desplegable con navegación por teclado. Maneja debounce, estados de carga, error y sin resultados automáticamente.

Props

| Prop | Tipo | Requerido | Por defecto | Descripción | |------|------|-----------|-------------|-------------| | path | string | No | — | Ruta de la API a consultar. Si se omite, se usa localData. | | apiBaseUrl | string | No | — | URL base del cliente HTTP. | | useAuthToken | boolean | No | false | Cuando es true, usa el cliente autenticado. | | localData | any[] | No | [] | Arreglo de datos a filtrar cuando no hay path. | | searchParam | string | No | — | Nombre del parámetro de query al usar path. | | placeholder | string | No | 'Search...' | Texto de placeholder del campo. | | minSearchLength | number | No | 1 | Caracteres mínimos para disparar la búsqueda. | | debounceTime | number | No | 300 | Milisegundos de espera tras la última tecla. | | maxResults | number | No | 10 | Máximo de resultados a mostrar. | | loadingText | string | No | 'Searching...' | Texto mientras se cargan los resultados. | | noResultsText | string | No | 'No results found.' | Texto cuando no hay resultados. | | errorText | string | No | 'An error occurred.' | Texto cuando la llamada a la API falla. | | disabled | boolean | No | false | Deshabilita el campo. | | defaultValue | string | No | '' | Valor inicial del campo. | | filters | any[] | No | — | Filtros adicionales enviados como parámetro filters. | | itemLabelKey | string | No | — | Clave del item usada como etiqueta principal. | | itemDescriptionKey | string | No | — | Clave del item usada como descripción secundaria. | | itemImageKey | string | No | — | Clave del item usada como URL de imagen. | | renderItem | (item, index, results) => ReactNode | No | — | Render personalizado de cada resultado. | | onSelect | (item: any) => void | No | — | Se ejecuta al seleccionar un resultado. | | onSearch | (query: string) => void | No | — | Se ejecuta en cada intento de búsqueda. | | loadingIndicator | ReactNode | No | — | Indicador de carga personalizado. | | containerStyle | React.CSSProperties | No | — | Estilos del contenedor externo. | | searchInputStyle | React.CSSProperties | No | — | Estilos del campo de texto. | | itemStyle | React.CSSProperties | No | — | Estilos de cada fila de resultado. | | popoverStyle | React.CSSProperties | No | — | Estilos del popover de resultados. |

Uso

Búsqueda en API remota

import Autocomplete from '@/components/Autocomplete';

export default function Example() {
  return (
    <Autocomplete
      apiBaseUrl="https://api.example.com"
      path="/v1/products/search"
      searchParam="q"
      itemLabelKey="name"
      itemDescriptionKey="sku"
      useAuthToken
      onSelect={(item) => console.log('Seleccionado:', item)}
    />
  );
}

Datos locales con render personalizado

import Autocomplete from '@/components/Autocomplete';

const ciudades = [
  { id: 1, name: 'Buenos Aires', country: 'Argentina' },
  { id: 2, name: 'Córdoba', country: 'Argentina' },
];

export default function Example() {
  return (
    <Autocomplete
      localData={ciudades}
      placeholder="Buscar ciudades..."
      renderItem={(item) => (
        <span>
          <strong>{item.name}</strong> — {item.country}
        </span>
      )}
      onSelect={(item) => console.log('Seleccionado:', item)}
    />
  );
}