AsyncSelect

Combobox that loads options remotely as you type, powered by a React Query fetcher.

AsyncSelect is a Combobox that fetches its options from a server as the user types. You supply queryFn (returns a promise of ComboboxOptions for the query) and queryKey (the React Query cache key for that query); loading and empty states are handled for you. Use minChars to avoid firing requests on short input and minCharsMessage to prompt the user. It is controlled via value/onChange like a regular Combobox.

Example

Preview

import { AsyncSelect } from '@officina/ui';
import { useState } from 'react';

function UserSearch() {
  const [value, setValue] = useState<string | null>(null);
  return (
    <AsyncSelect
      value={value}
      onChange={setValue}
      minChars={2}
      placeholder="Search users…"
      queryKey={(query) => ['users', query]}
      queryFn={async (query) => {
        const res = await fetch(`/api/users?q=${query}`);
        const users = await res.json();
        return users.map((u) => ({ value: u.id, label: u.name }));
      }}
    />
  );
}

API

Prop	Type	Default	Description
onChange*	(value: T \| null) => void	—	Called with the chosen value (or null when cleared).
queryFn*	(query: string) => Promise<ComboboxOption<T>[]>	—
queryKey*	(query: string) => unknown[]	—
value*	T \| null	—	Currently selected value, or null.
clearable	boolean	—	Show a clear button to reset the selection.
disabled	boolean	—	Disables the input and prevents selection.
emptyMessage	string	—	Message shown when no options match the query.
invalid	boolean	—	Marks the field invalid for validation styling and `aria-invalid`.
minChars	number	1
minCharsMessage	string	—
name	string	—	Form field name for the underlying input.
placeholder	string	—	Placeholder text for the input when nothing is selected.
renderOption	(option: ComboboxOption<T>) => ReactNode	—	Custom renderer for an option row.
required	boolean	—	Marks the field as required for validation styling and `aria-required`.
size	enum	—	Control size.

Example

API

On this page