Forms

Autocomplete

Free-text input with sync or async suggestions.

Import

tsx

import { Autocomplete } from "@cooud-ui/ui";

bash

npx cooud-ui add autocomplete

Examples

Default

Free-text input that filters a static `options` list as you type. Arrow keys move the highlight, Enter commits it, and Escape dismisses the suggestions.

tsx

const frameworks: AutocompleteOption[] = [
  { value: "Next.js" },
  { value: "Remix" },
  { value: "Astro" },
  { value: "SvelteKit" },
  { value: "Nuxt" },
  { value: "SolidStart" },
];

function AutocompleteDemo() {
  const [value, setValue] = useState("");

  return (
    <Autocomplete
      options={frameworks}
      value={value}
      onValueChange={setValue}
      placeholder="Search a framework…"
      aria-label="Framework"
      className="max-w-xs"
    />
  );
}

Async suggestions

Pass `onSearch` to resolve suggestions remotely. Calls are debounced, stale responses are dropped, and the busy state (spinner + skeletons) is managed for you.

tsx

function AutocompleteAsyncDemo() {
  const [value, setValue] = useState("");

  // Debounced; the component tracks its own loading state when onSearch is set.
  const search = async (query: string): Promise<AutocompleteOption[]> => {
    const res = await fetch(`/api/frameworks?q=${encodeURIComponent(query)}`);
    return res.json();
  };

  return (
    <Autocomplete
      onSearch={search}
      value={value}
      onValueChange={setValue}
      placeholder="Search (async)…"
      aria-label="Framework (async)"
      className="max-w-xs"
    />
  );
}

API Reference

Generated from the component's exported types.

AutocompleteProps

Extends Omit< InputHTMLAttributes<HTMLInputElement>, "value" | "defaultValue" | "onChange" | "onSelect" | "role" >

Prop	Type	Default	Description
`options`	`AutocompleteOption[]`	—	Static suggestions. When omitted, provide `onSearch` to fetch suggestions for the current query asynchronously.
`onSearch`	`(query: string) => Promise<AutocompleteOption[]>`	—	Async resolver invoked (debounced) with the current query. Return the suggestions to render. Use together with `loading` for the busy state, or let the component manage `loading` automatically when `options` is omitted.
`value`	`string`	—	Controlled free-text value. Pair with `onValueChange`.
`defaultValue`	`string`	—	Initial value for uncontrolled usage.
`onValueChange`	`(value: string) => void`	—	Called with the new free-text value on every keystroke or selection.
`onSelect`	`(option: AutocompleteOption) => void`	—	Called when a suggestion is committed (click / Enter on a highlight).
`placeholder`	`string`	`"Type to search…"`	Placeholder for the text input.
`emptyText`	`string`	`"No results found."`	Message rendered when there are no suggestions for the query.
`loading`	`boolean`	—	Forces the busy state (spinner + skeletons). When `onSearch` is provided and this is left undefined, the component tracks pending searches itself.
`debounceMs`	`number`	`200`	Debounce, in ms, before `onSearch` fires or local filtering re-runs.
`allowCustomValue`	`boolean`	`true`	When true (default), the committed value can be free text that is not in the suggestion list. When false, blurring or Enter with non-matching text reverts to the last valid value.
`disabled`	`boolean`	`false`	Disable the whole control.
`contentClassName`	`string`	—	Extra classes for the popover content.
`loadingSkeletonRows`	`number`	`3`	Number of skeleton rows to show while loading.