Forms

Autocomplete

Free-text input with sync or async suggestions.

Import

tsx

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

bash

npx cronus-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"
    />
  );
}

.cronus

The same component declared in Cronus. Emitted at build time from the audit fixtures — the kernel renders it as HTML with no React.

PortedParity: DiffGeometry 1/1Pixel diff 1836 pxLogic 1/1Parity scoreboard

default.cronus

app "audit-fixtures" {
  port 5176
}

style {
  preset aurora
  theme dark
}

component AutocompleteDefault layout:inline style:autocomplete {
  value:"L"
  aria-label:"City"
  label "Type a city"
  text "Type a city"
  text "Lisbon"
  text "Lima"
  text "London"
}

page "/audit/autocomplete/default" type:custom {
  use AutocompleteDefault
}

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.
`name`	`string`	—	Submitted name when used in a form.
`required`	`boolean`	—	Marks the control as required.
`className`	`string`	—	Additional class names merged onto the root.