Autocomplete

Autocomplete is a field whose suggestions arrive as you type, so a long list becomes a short one before it becomes a choice. It differs from Dropdown in that the control is a text field rather than a button: nothing has to be chosen, and the reader can keep typing. It differs from MultiSelect in that it holds one value, not several. Turn on allowCustomValue and whatever is typed becomes the value; leave it off and only a suggestion can.

Usage

import { Autocomplete } from "@asheeui/web";

const frameworks = [
  { label: "React", value: "react" },
  { label: "Vue", value: "vue" },
];

<Autocomplete
  label="Framework"
  options={frameworks}
  onValueChange={(value) => save(value)}
/>

Each option is a label and a value, with an optional disabled. The selection is controlled: value decides which option is shown as chosen, and onValueChange reports both the value and the option, so a caller that needs the label does not have to look it up. The text in the field is the component's own unless you need it, onInputChange reports every keystroke, which is where a remote search or a character count starts.

Suggestions

The suggestion list is the framework's menu, the same listbox Dropdown and MultiSelect open, filtered on the option's label as the reader types. The filter is a case-insensitive substring, so land finds Ireland; an empty field shows the whole list. An option marked disabled is still listed, and the arrow keys pass over it rather than landing on it.

The list's own appearance is configured through menu, and everything in that object belongs to the menu rather than to the field: portal (default true) and portalTarget decide where the list is rendered, lockScroll (default true) whether the page behind it moves, and itemVariant (ghost), activeItemVariant (faded), itemColor, activeItemColor, size and radius how its options are drawn. belowList renders a node under the last option, a note, an add control, a hint, inside the same panel.

Free text

An autocomplete usually refuses what it does not recognise. allowCustomValue removes that rule: while it is true every keystroke reports the raw text through onValueChange, so the field's value is whatever is in it, and a suggestion is a shortcut rather than a requirement.

A value that is not on the list is displayed as the text the reader left behind. If the suggestions run out, the panel says so in a status region and the field still holds the typed text, the list is advice, and the value is the reader's.

Props

The defaults are a cascade rather than a list. The component registers the field family's web defaults, so size is md and variant is bordered; radius follows the application's defaultRadius and the accent follows its defaultColor, so a product that rounds everything to full states it once. options is empty until you pass a list, allowCustomValue is off, and the placeholder is Type to search... unless you state one.

Accessibility

• The field is a combobox: the input carries aria-expanded and aria-autocomplete="list", and while a suggestion is current it names that suggestion through aria-activedescendant. The list is a listbox whose rows are options with aria-selected.
• Focus never leaves the input: the suggestion list opens without taking focus and does not take it back when it closes, so the reader keeps typing while a suggestion is current, the pattern the combobox role describes.
• ArrowDown and ArrowUp move through the options and wrap at the ends, Home and End jump to the first and last reachable ones, Enter chooses the current option, and Escape closes the list. Disabled options are skipped by all of them, so Enter can never take one.
• The label names the input through htmlFor, and the description and the message are wired to it through aria-describedby; an error message is announced as an alert, and a search that matches nothing says "No options found" in a status region instead of leaving a blank panel.

Related