AutocompleteField

AutocompleteField renders a text input that debounces user input and queries a remote API to show matching options in a popover. It supports single and multiple selections displayed as pills, keyboard navigation (arrow keys + Enter), and an optional inline "create" button that opens a form modal to add new records.

Props

| Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | apiBaseUrl | string | Yes | — | Base URL of the API used for search requests. | | searchPath | string | Yes | — | Path appended to apiBaseUrl for search requests (e.g. /v1/products). | | value | any \| any[] | No | '' / [] | Currently selected value(s). Pass an array when multiple is true. | | onChange | (selectedValue: any \| any[]) => void | Yes | — | Called with the new selection on every change. | | label | string | No | — | Label rendered above the input. | | description | string | No | — | Helper text rendered below the component. | | options | { [key: string]: any }[] | No | [] | Static fallback options (shown when the search term is empty). | | multiple | boolean | No | false | Allow selecting more than one item. Selected items are shown as pills. | | placeholder | string | No | 'Escriba para buscar...' | Placeholder text for the search input. | | useAuthToken | boolean | No | true | Whether to attach the auth token to search requests. | | searchParam | string | No | — | Query-string key for the search term (e.g. 'search'). When omitted the term is appended as a path segment. | | noResultsText | string | No | 'No results found' | Text shown in the popover when the search returns no results. | | searchingText | string | No | 'Searching...' | Text shown in the popover while the request is in-flight. | | itemLabelKey | string | No | 'name' | Key in each result object used as the display label. | | itemDescriptionKey | string | No | — | Key in each result object used as a secondary description line. | | itemImageKey | string | No | — | Key in each result object used as an image URL (displayed as a small avatar). | | itemLabelStyle | React.CSSProperties | No | — | Styles applied to the label inside each option. | | itemDescriptionStyle | React.CSSProperties | No | — | Styles applied to the description inside each option. | | itemImageStyle | React.CSSProperties | No | — | Styles applied to the avatar image inside each option. | | allowCreate | boolean | No | false | Show a button to open the creation modal. | | createPath | string | No | — | API path used by the creation form modal (POST). | | formFields | Field[] | No | [] | Field definitions for the creation form modal. | | formTitle | string | No | 'Crear nuevo registro' | Title of the creation modal. | | formButtonTitle | string | No | 'Crear nuevo' | Send-button label in the creation modal. | | formButtonText | string | No | — | Alias for the send-button label. | | formWidth | number \| string | No | 500 | Width of the creation modal. | | onCreateSuccess | (newRecord: any) => void | No | — | Called after a record is successfully created. | | onCreateError | (error: any) => void | No | — | Called when the creation request fails. | | createButtonType | 'solid' \| 'clear' \| 'outline' | No | 'solid' | Visual style of the create button. | | createButtonSize | 'sm' \| 'md' \| 'lg' | No | 'sm' | Size of the create button. | | createButtonColor | string | No | themeColors.light | Color of the create button. | | createButtonIcon | string | No | 'add' | Icon name for the create button. | | containerStyle | React.CSSProperties | No | {} | Styles applied to the root container div. | | labelStyle | React.CSSProperties | No | {} | Styles applied to the label element. | | descriptionStyle | React.CSSProperties | No | {} | Styles applied to the description paragraph. | | popoverStyle | React.CSSProperties | No | {} | Styles applied to the results popover inner div. |

Usage

Basic single selection

import React, { useState } from 'react';
import AutocompleteField from '@/components/fields/AutocompleteField';

export default function Example() {
  const [product, setProduct] = useState(null);

  return (
    <AutocompleteField
      label="Product"
      apiBaseUrl="https://api.example.com"
      searchPath="/v1/products"
      searchParam="search"
      value={product}
      onChange={setProduct}
      itemLabelKey="name"
    />
  );
}

Multiple selection with image avatar

<AutocompleteField
  label="Assign users"
  apiBaseUrl="https://api.example.com"
  searchPath="/v1/users"
  searchParam="q"
  multiple={true}
  value={selectedUsers}
  onChange={setSelectedUsers}
  itemLabelKey="full_name"
  itemDescriptionKey="email"
  itemImageKey="avatar_url"
/>

With inline create modal

<AutocompleteField
  label="Category"
  apiBaseUrl="https://api.example.com"
  searchPath="/v1/categories"
  searchParam="search"
  value={category}
  onChange={setCategory}
  allowCreate={true}
  createPath="/v1/categories"
  formTitle="New Category"
  formFields={[
    { type: 'text', name: 'name', label: 'Name' },
  ]}
  onCreateSuccess={(rec) => console.log('Created', rec)}
/>