# Core/AutocompleteField - Design

AutocompleteField combines a text field with a suggestions list. Consumers can supply static `AutocompleteField.Item` children or an `items` collection with an optional default item renderer. The field allows custom values that are not in the list.

## Anatomy

1. **Text input** — Entry is through a standard text input. The field keeps focus while the list is open so typing and keyboard
   navigation stay in one place.
2. **ListBox** — Filtered results appear in a ListBox under the field.

## Properties

### Label

A label is required for input fields and succinctly describes the field’s purpose. If another text element is acting
as the label, like a section title, ensure the proper aria relationships are linked.

### Placeholder text

<p>
  Placeholder text is visible until a character is entered.
</p>

<p>
  Because the placeholder text disappears, putting instructions or requirements as placeholder text is not
  accessible. Helper text is the preferred method to convey this information.
</p>

### Helper text

Helper text is placed below the field and informs the user of any requirements, disclaimers, and errors. Helper text
is shown persistently but is replaced by error text when an error occurs.

### Layout

There are two layouts available for text fields, vertical and horizontal. Vertical labels are the preferred layout,
appearing above the field. Horizontal labels appear on the leading side of the field, and should only be used when
space is limited.

## Layout and spacing

* Input renders identically to [TextField](?path=/docs/core-textfield--design).
* Suggestions are presented using a ListBox.

## Behavior

### Autocomplete vs. Select

<p>
  **Autocomplete** is an input box with text hints that users can type freely into. Hints are presented and refined
  ina selection list as the user types. Freeform entry is allowed.
</p>

<p>
  **Select**

   allows selecting options only among a given set of choices.
</p>

### Filtering

As the user types into the text field options are filtered based on the value.

## Best Practices

Do:

* Do show a "no results" message when the filter returns nothing.
* Do support keyboard-only navigation of suggestions.

Don't:

* Don't use AutocompleteField for small mutually exclusive sets (about seven or fewer visible options) — use [RadioGroup](?path=/docs/core-radiogroup--design) or Select.
* Don't use AutocompleteField for plain freeform text with no list validation — use [TextField](?path=/docs/core-textfield--design).
* Don't require picking from the list while still allowing arbitrary text without explaining that behavior.

## Accessibility

* `role="combobox"` on the input, `aria-expanded` reflects list open state.
* `aria-controls` references the suggestion list `id`.
* `aria-activedescendant` references the currently focused suggestion.
* Suggestion list: `role="listbox"`, each suggestion: `role="option"`.

### Keyboard interaction

* Keyboard interactions follow Select and ListBox.

## Related components

* [TextField](?path=/docs/core-textfield--design) — For freeform text without suggestions.
* [RadioGroup](?path=/docs/core-radiogroup--design) — For small mutually exclusive option sets.