Components

AsyncComboboxField

Combobox with debounced async search, loading state, and integrated label and error message.

Category: Form / Standalone

Import

import {
  AsyncComboboxField,
  type AsyncComboboxFieldProps,
  type AsyncComboboxItem,
} from "@hareru/ui"

Exports

NameTypeDescription
AsyncComboboxFieldComponentAsync combobox with label
AsyncComboboxFieldPropsTypeProps interface
AsyncComboboxItemType{ value: string; label: string; [key: string]: unknown }

Key Props

PropTypeDefaultDescription
labelstring—Field label (required)
fetchUrlstring—URL endpoint for fetching options (required)
placeholderstring"Search..."Input placeholder
queryParamstring"q"Query parameter name appended to fetchUrl
valuestring—Controlled selected value
onValueChange(value: string, item?: AsyncComboboxItem) => void—Called when selection changes
debounceMsnumber300Debounce delay in milliseconds
mapResponse(data: unknown) => AsyncComboboxItem[]—Custom response mapper (defaults to data.accounts ?? data.items ?? data)
requiredboolean—Shows required indicator
errorstring—Error message displayed below the field

Accessibility

  • Roles: combobox
  • Keyboard:
    • Arrow keys to navigate options
    • Enter to select
    • Escape to close
  • Notes: Integrates label, input, and listbox with automatic aria linkage.

Usage

import { AsyncComboboxField } from "@hareru/ui"

// Basic usage
<AsyncComboboxField
  label="Account"
  fetchUrl="/api/accounts"
  value={selectedAccount}
  onValueChange={(value, item) => setSelectedAccount(value)}
/>

// With custom response mapping and debounce
<AsyncComboboxField
  label="Customer"
  fetchUrl="/api/customers/search"
  queryParam="name"
  debounceMs={500}
  mapResponse={(data) =>
    (data as { results: Array<{ id: string; name: string }> }).results.map(
      (c) => ({ value: c.id, label: c.name })
    )
  }
  required
/>

// With error
<AsyncComboboxField
  label="Product"
  fetchUrl="/api/products"
  error="Please select a product"
/>

Notes

  • Built on top of the Combobox component — wraps ComboboxTrigger, ComboboxContent, ComboboxInput, ComboboxList, and ComboboxItem.
  • Fetches options automatically as the user types, with configurable debounce delay.
  • Default response mapping tries data.accounts, data.items, then falls back to data as an array. Use mapResponse for custom API shapes.
  • The required prop adds a visual asterisk after the label.

FormField

Composite form field providing accessible label, control, description, and error message wiring via context.

Badge

Compact status label with semantic color variants.

On this page

ImportExportsKey PropsAccessibilityUsageNotes