Forms · astro-ui · Autocomplete

AutocompleteJS

Input that suggests options as you type — ARIA combobox pattern.

Autocomplete pairs a text input with a filtered suggestion list using the WAI-ARIA combobox + listbox pattern. Type to filter (case-insensitive substring on label/value), move with ↑/↓, commit with Enter, dismiss with Escape, jump with Home/End. Options render server-side; a small scoped script handles filtering and focus. The committed value posts with the form under the field’s name — a native input underneath, so forms and autofill behave.

← All components

Features

Full keyboard support: ↑/↓ navigate, Enter commits, Escape closes, Home/End jump
Case-insensitive substring filtering; filter={false} for async/external results
Grouped options with labelled sections
autoHighlight, clearable button, openOnFocus, and top/bottom placement
Five sizes and eight border variants matching Input
Committed value posts with the form under name — native input underneath

Usage

---
import { Autocomplete } from "astro-ui";
---

<Autocomplete
  name="framework"
  placeholder="Pick a framework…"
  items={["Astro", "Next.js", "Nuxt", "SvelteKit"]}
  clearable
/>

Demos

Basic

<Autocomplete
  name="framework"
  placeholder="Pick a framework…"
  items={["Astro", "Next.js", "Nuxt", "SvelteKit", "Remix"]}
/>

Options with hints

<Autocomplete
  name="city"
  items={[
{ value: "jp-tokyo", label: "Tokyo", hint: "Japan" },
{ value: "fr-paris", label: "Paris", hint: "France" },
{ value: "us-nyc", label: "New York", hint: "United States" },
  ]}
/>

Groups

<Autocomplete
  name="stack"
  groups={[{ label: "Frontend", items: ["Astro", "Next.js"] }, { label: "Backend", items: ["Node", "Deno"] }]}
/>

Sizes

<Autocomplete size="xs" items={…} />
<Autocomplete size="sm" items={…} />
<Autocomplete size="md" items={…} />
<Autocomplete size="lg" items={…} />

Clearable + open on focus

<Autocomplete name="search" clearable openOnFocus items={["One", "Two", "Three"]} />

API

Props

Prop	Type	Default	Description
`items`	`(string \| { value, label, hint? })[]`	`[]`	Suggestion list; strings become both value and label.
`groups`	`{ label, items }[]`	`—`	Labelled sections; overrides items when set.
`name`	`string`	`—`	Form field name; committed value posts with the form.
`value`	`string`	`—`	Initial committed value (server-side preselect).
`placeholder`	`string`	`"Search…"`	Input placeholder text.
`emptyMessage`	`string`	`"No results found."`	Shown when the filter matches nothing.
`filter`	`boolean`	`true`	Client-side substring filter; disable for async filtering.
`autoHighlight`	`boolean`	`false`	Highlight the first match when the list opens.
`clearable`	`boolean`	`false`	Render a clear (✕) button when the field has a value.
`openOnFocus`	`boolean`	`false`	Open the list on focus (search-style).
`size`	`"xs" \| "sm" \| "md" \| "lg" \| "xl"`	`"md"`	Control size (heights mirror Input).
`variant`	`"inherit" \| "primary" \| … \| "info"`	`"inherit"`	Border color variant (mirrors Input).
`placement`	`"bottom" \| "top"`	`"bottom"`	Which side the panel opens on.
`disabled / required / invalid`	`boolean`	`false`	Native states + invalid styling hook.
`class`	`string`	`—`	Merged via cn(); Tailwind classes welcome.
`id`	`string`	`—`	Element id.

Accessibility

Implemented accessibility features — semantics, ARIA wiring, and keyboard behavior that ship with the component.

FAQ

How is this different from Select?

Select is the native <select> — zero JS, platform keyboard handling, always fully accessible. Autocomplete adds type-to-filter and free typing at the cost of a small script. Prefer Select when the option set is small and fixed.

Can I filter against an API?

Yes — set filter={false} so the script doesn't filter client-side, then listen for input events and render your own options into the listbox panel (or re-render the whole component server-side per request).

Changelog

Version history mentioning Autocomplete.

v0.1.0 — 2026-11-11

added

Forms (18): Autocomplete, Combobox, Label, Field, Input, InputGroup, Textarea, Select, Checkbox, Radio, Switch, Toggle, ToggleGroup, RadioGroup, Rating, Slider, DatePicker, TimePicker.