Autocomplete

A text input that searches either a remote API endpoint or a local data array as the user types. Results appear in a dropdown popover with keyboard navigation support. The component handles debouncing, loading states, error states, and empty states automatically.

Props

| Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | path | string | No | — | API path to call. If omitted, localData is searched instead. | | apiBaseUrl | string | No | — | Base URL for the API client. Overrides the default client base URL. | | useAuthToken | boolean | No | false | When true, uses the authenticated HTTP client. | | localData | any[] | No | [] | Array of items to search when no path is provided. | | searchParam | string | No | — | Query parameter name appended when using path. If omitted, the value is appended as a path segment. | | placeholder | string | No | 'Search...' | Placeholder text for the input. | | minSearchLength | number | No | 1 | Minimum number of characters before a search is triggered. | | debounceTime | number | No | 300 | Milliseconds to wait after the last keystroke before searching. | | maxResults | number | No | 10 | Maximum number of results to display. | | loadingText | string | No | 'Searching...' | Text shown while results are loading. | | noResultsText | string | No | 'No results found.' | Text shown when the search returns no items. | | errorText | string | No | 'An error occurred.' | Text shown when the API call fails. | | disabled | boolean | No | false | Disables the input. | | defaultValue | string | No | '' | Initial value of the input. | | filters | any[] | No | — | Additional filter objects serialized and appended as a filters query parameter. | | itemLabelKey | string | No | — | Key of each result item used as the primary label. | | itemDescriptionKey | string | No | — | Key of each result item used as the secondary description. | | itemImageKey | string | No | — | Key of each result item used as the image URL. | | renderItem | (item, index, results) => ReactNode | No | — | Custom render function for each result item. Overrides itemLabelKey, itemDescriptionKey, and itemImageKey. | | onSelect | (item: any) => void | No | — | Callback fired when a result item is selected. | | onSearch | (query: string) => void | No | — | Callback fired on every search attempt. | | loadingIndicator | ReactNode | No | — | Custom loading indicator, replaces the default loading text. | | containerStyle | React.CSSProperties | No | — | Inline styles for the outer container. | | searchInputStyle | React.CSSProperties | No | — | Inline styles for the text input. | | itemStyle | React.CSSProperties | No | — | Inline styles for each result row. | | itemLabelStyle | React.CSSProperties | No | — | Inline styles for the item label text. | | itemDescriptionStyle | React.CSSProperties | No | — | Inline styles for the item description text. | | itemImageStyle | React.CSSProperties | No | — | Inline styles for the item image. | | popoverStyle | React.CSSProperties | No | — | Inline styles for the results popover container. |

Usage

Remote API search

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('Selected:', item)}
    />
  );
}

Local data search with custom render

import Autocomplete from '@/components/Autocomplete';

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

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