Autocomplete

An autocomplete puts a text input in front of a list of options: typing filters the list, the arrow keys move a highlight through it while focus stays in the input, and Enter or a press chooses the highlighted option. The list is always shown under the input, as in a filter list, a command list in a dialog or the results under a search box. The highlighted option is the input’s aria-activedescendant.

Choosing selects the option, as on Listbox, and reports action. The text stays as it is, so what a choice does is yours: keep the selection, run a command, or clear the text for the next search. For a list in a popup, with a value the text settles into, use Combobox, which is built on Autocomplete.

It follows the WAI-ARIA Combobox pattern with list autocomplete, its list always expanded.

<!doctype html><meta charset="utf-8"><style>/* The page's layout. The autocomplete's look is @uniaria/styles' default. */
:root {
  font:
    15px/1.5 system-ui,
    sans-serif;
}
body {
  display: grid;
  gap: 1rem;
  margin: 1.5rem;
  background: var(--uni-surface-color);
  color: var(--uni-text-color);
}
.row {
  display: flex;
  flex-wrap: wrap;
  gap: 2rem;
  align-items: start;
}
.row > uni-autocomplete {
  inline-size: 15rem;
}
[data-uni='autocomplete'] [data-element='List'] {
  max-block-size: 15rem;
}
output {
  padding-block: 0.5rem;
}
</style><div class="row">
  <uni-autocomplete
    id="fruit"
    selection-mode="multiple"
    highlight-first-match
    disabled-keys='["durian"]'
  >
    <div data-uni="autocomplete">
      <label data-element="Label">Fruit</label>
      <input data-element="Input" type="search" placeholder="Filter" />
      <div data-element="List">
        <div data-element="Option" data-key="apple">Apple</div>
        <div data-element="Option" data-key="apricot">Apricot</div>
        <div data-element="Option" data-key="banana">Banana</div>
        <div data-element="Option" data-key="blueberry">Blueberry</div>
        <div data-element="Option" data-key="cherry">Cherry</div>
        <div data-element="Option" data-key="durian">Durian</div>
        <div data-element="Group" data-key="citrus">
          <span data-element="GroupLabel" data-key="citrus">Citrus</span>
          <div data-element="Option" data-key="lemon">Lemon</div>
          <div data-element="Option" data-key="lime">Lime</div>
          <div data-element="Option" data-key="orange">Orange</div>
        </div>
        <div data-element="Option" data-key="grape">Grape</div>
        <div data-element="Option" data-key="kiwi">Kiwi</div>
        <div data-element="Option" data-key="mango">Mango</div>
        <div data-element="Option" data-key="peach">Peach</div>
        <div data-element="Option" data-key="pear">Pear</div>
      </div>
      <p data-element="Empty">No fruit matches.</p>
      <p data-element="Description">Pick as many as you like.</p>
    </div>
  </uni-autocomplete>
  <output id="log">Type “ma”, press Enter, then Escape.</output>
</div>
<script src="/demo/autocomplete.js"></script><script>const fruit = document.getElementById('fruit');
const log = document.getElementById('log');

// `defaultValue` is a property: markup has no attribute for it.
fruit.defaultValue = ['banana'];

let value = fruit.defaultValue;
let text = '';

const show = () => {
  log.textContent = `value: [${value.join(', ')}] · text: “${text}”`;
};

// Enter or a press toggles an option; the text only filters the list.
fruit.addEventListener('valuechange', (event) => {
  value = event.detail;
  show();
});
fruit.addEventListener('inputchange', (event) => {
  text = event.detail;
  show();
});
</script>

import { autocomplete } from '@uniaria/core/autocomplete';
import { useBehavior } from '@uniaria/react';

const fruits = [
  { key: 'apple', textValue: 'Apple' },
  { key: 'banana', textValue: 'Banana' },
  { key: 'cherry', textValue: 'Cherry' },
];

export function FruitFilter() {
  const fruit = useBehavior(autocomplete, {
    items: fruits,
    selectionMode: 'multiple',
  });
  return (
    <div {...fruit.parts.root}>
      <label {...fruit.parts.label}>Fruit</label>
      <input {...fruit.parts.input} type="search" />
      <div {...fruit.parts.list}>
        {fruits.map((item) => (
          <div key={item.key} {...fruit.getItemProps('option', item.key)}>
            {item.textValue}
          </div>
        ))}
      </div>
      <p {...fruit.parts.empty}>No fruit matches</p>
    </div>
  );
}

<script setup lang="ts">
import { autocomplete } from '@uniaria/core/autocomplete';
import { useBehavior } from '@uniaria/vue';

const fruits = [
  { key: 'apple', textValue: 'Apple' },
  { key: 'banana', textValue: 'Banana' },
  { key: 'cherry', textValue: 'Cherry' },
];

const fruit = useBehavior(autocomplete, {
  items: fruits,
  selectionMode: 'multiple',
});
</script>

<template>
  <div v-bind="fruit.parts.root">
    <label v-bind="fruit.parts.label">Fruit</label>
    <input v-bind="fruit.parts.input" type="search" />
    <div v-bind="fruit.parts.list">
      <div
        v-for="item in fruits"
        :key="item.key"
        v-bind="fruit.getItemProps('option', item.key)"
      >
        {{ item.textValue }}
      </div>
    </div>
    <p v-bind="fruit.parts.empty">No fruit matches</p>
  </div>
</template>

<uni-autocomplete selection-mode="multiple">
  <div data-uni="autocomplete">
    <label data-element="Label">Fruit</label>
    <input data-element="Input" type="search" />
    <div data-element="List">
      <div data-element="Option" data-key="apple">Apple</div>
      <div data-element="Option" data-key="banana">Banana</div>
      <div data-element="Option" data-key="cherry">Cherry</div>
    </div>
    <p data-element="Empty">No fruit matches</p>
  </div>
</uni-autocomplete>

<script type="module">
  import '@uniaria/elements/autocomplete';
</script>

Render every option, matching or not: UniAria hides the ones the typed text leaves out. The options are Listbox’s item parts, so keys, groups, option labels, descriptions and extras, and items read from the markup work as on Listbox.

Render the root part around the others. Focus within it is what focuschange reports, the input and the list taken as one, and the default styles key on it.

By default an option matches when its text contains the typed text, trimmed, ignoring case and accents, in the field’s language: locale, else the nearest lang attribute, else the browser’s. Group labels aren’t searched; a group with no match left is hidden with its label.

• From the start. The text always filters: a defaultInputValue, a text you set and the text a form reset puts back filter the list too. showAll() shows every option again and keeps the text, until the user types.
• What it hides. Options and groups left out get the hidden attribute, the arrow keys skip them, and they don’t count in the option count. If your CSS sets display on options, keep [hidden] hiding them.
• No matches. isEmpty and data-empty are set, and the empty part shows and describes the list. The list stays shown.

Pass your own filter to match differently. It gets each option’s text, the trimmed input text, and the item as items holds it, so it can match more than the text:

interface Fruit {
  key: string;
  textValue: string;
  keywords: readonly string[];
}

const byKeyword = (textValue: string, inputValue: string, item: Fruit) =>
  [textValue, ...item.keywords].some((word) =>
    word.toLowerCase().includes(inputValue.toLowerCase()),
  );

filter: false shows items as you give them, for filtering on a server from inputchange:

const [query, setQuery] = useState('');
const cities = useCitySearch(query); // your data
const city = useBehavior(autocomplete, {
  items: cities,
  filter: false,
  onInputChange: setQuery,
});

On the element, filter is a property: element.filter = byKeyword.

By default typing clears the highlight, and ArrowDown starts it at the first match. With shouldHighlightFirstMatch (highlight-first-match), typing highlights the first match at once, so Enter chooses it:

• The first match is the first shown option that is selected and enabled, else the first enabled one. It scrolls into view.
• When the matches change while typing holds the highlight, such as results arriving with filter: false, the first match is highlighted again. Once the arrows or the mouse move the highlight, it stays where they put it.
• Deleting, pasting, undoing, redoing and Escape clear the highlight.
• The input’s aria-activedescendant follows half a second after the last keystroke, so a screen reader still reads the typed character. The arrows and the mouse set it at once.

A press or Enter on the highlighted option selects it, as on Listbox, and reports action with its key. Nothing else changes: the text, the filter and the highlight stay. Act on action for what a choice does, such as starting the next search afresh:

const [query, setQuery] = useState('');
const search = useBehavior(autocomplete, {
  items: pages,
  inputValue: query,
  onInputChange: setQuery,
  onAction: (key) => {
    openPage(key); // yours
    setQuery('');
  },
});

• Choosing the selected option again keeps it selected in single mode and still reports action.
• Multiple mode (selectionMode: 'multiple'): Enter and a press toggle an option. Space types, and Shift with the arrows and Ctrl+A edit the text, so Listbox’s range keys don’t apply; Shift with a press still selects a range.
• Enter with nothing highlighted isn’t handled, so a form around the input submits.

Neither the text nor the selection is a form value of its own:

• Give the input a name to submit its text, as with any input. The selection isn’t submitted: read value.
• isRequired sets aria-required and data-required only, not the native required, so an empty search never blocks a submit.
• Resetting the form puts back the default text, which filters the list again, and keeps the selection (see Reset).

const [value, setValue] = useState<readonly string[]>([]);
const [inputValue, setInputValue] = useState('');
const fruit = useBehavior(autocomplete, {
  items: fruits,
  value,
  onValueChange: setValue,
  inputValue,
  onInputChange: setInputValue,
});

<script setup lang="ts">
const value = ref<readonly string[]>([]);
const inputValue = ref('');
const fruit = useBehavior(autocomplete, () => ({
  items: fruits,
  value: value.value,
  onValueChange: (keys) => (value.value = keys),
  inputValue: inputValue.value,
  onInputChange: (text) => (inputValue.value = text ?? ''),
}));
</script>

const fruit = document.querySelector('uni-autocomplete');
fruit.inputValue = '';
fruit.addEventListener('inputchange', (event) => {
  fruit.inputValue = event.detail;
});

The option count is English by default. Replace it whole:

const fruit = useBehavior(autocomplete, {
  items: fruits,
  optionCountAnnouncement: (count) =>
    count === 1 ? '1 Option verfügbar' : `${count} Optionen verfügbar`,
});

On the element, optionCountAnnouncement is a property.

Autocomplete takes Listbox’s virtualization props and passes them to its list. Put the scroller part around the list, give it a height, and render the renderedKeys state as on Listbox. While the user filters, renderedKeys holds only matching options.

Autocomplete takes Listbox’s option tooltip: one Tooltip with shouldOpenOnlyWhenTruncated and relation: 'none', which shows the whole text of a cut-off option. Pass its instance as optionTooltip, or on the element name it by id with the option-tooltip attribute, and render it inside the root, after the list. It follows the highlight, which the keys move, and the pointer. Typing or editing the text closes it until a key moves the highlight again.

A part keeps an id you give it, and everything that refers to the part follows it; UniAria writes an id only on a part that has none (see Ids).

The item parts are Listbox’s: option, optionLabel, optionDescription, optionExtras, group and groupLabel, inside the list and keyed by the item’s key (see Listbox). They carry no tabindex, since they never take focus.

The list is always vertical, and its options never take focus. Development builds warn when the input or the list has no name: render a label part or pass labelledBy. An aria-label on the input names the input only.

The element dispatches each event on itself, bubbling, with the detail in event.detail.

In React and Vue it is on the handle (fruit.actions.showAll()); on the custom element it is a method (document.querySelector('uni-autocomplete').showAll()). open() and close() are there too, and do nothing: the list is always shown.

Select what you render, and the component renders again only when it changes:

const isEmpty = useBehaviorState(fruit, (state) => state.isEmpty);

On the custom element, read element.instance.getState(). See State.

“Named parts” are every part except scroller. State attributes are present or absent, never "false". The input carries the named parts’ attributes, and no data-hovered or data-focused of its own; it also has the native readonly and disabled, for :read-only and :disabled. The list and the scroller are tabindex="-1".

The optional @uniaria/styles package styles every part, as in the demo above, whose CSS tab holds only the page’s layout and the list’s height. The input is the field’s box, as Field draws a native input, and keeps its ring while the keys move the highlight, since focus stays in it. The list under it and the options are Listbox’s: an option’s text takes one line and ends in an ellipsis, so pair the list with an option tooltip, and its extras sit before the check. When nothing matches, the empty part shows inside the list’s box, in an option’s place; for that, render the label, the input and the list first, in that order. Virtualized, the scroller is the box. The height stays yours.

On the input. Keys with Ctrl or Meta, and every key while an input method is composing, stay with the browser.

• Focus stays in the input. The highlighted option is the input’s aria-activedescendant, written only once the option’s element exists. The list and options never take focus, and a mouse press in the list brings focus back to the input. A highlight moved by the keys scrolls into view, which browsers don’t do for aria-activedescendant.
• Always expanded. The input is a combo box with aria-expanded="true" that controls the list, since the list is always shown. Escape clears the text rather than closing anything.
• The mouse highlights an option only while focus is in the root, and only as it moves, so a resting pointer leaves nothing for Enter to choose after tabbing in, even when the page scrolls under it. A tap on a touch screen chooses an option without focusing the input, so the on-screen keyboard stays closed.
• The option count is announced politely whenever the number of shown options changes while focus is in the root: typing, results arriving, Escape, showAll() or a text you set. Never on focus. Matching disabled options count too. Translate it with optionCountAnnouncement.
• Spoken output. The input reads “combobox, Fruit, has popup listbox, expanded, autocomplete in list”, and while an option is highlighted, “active descendant Banana”. The list reads “listbox, Fruit, orientated vertically”, with “multi-selectable” in multiple mode. Filtered-out options aren’t read.
• Nothing is highlighted while typing unless you ask for it: NVDA stops reading typed characters while an active descendant is set, so with shouldHighlightFirstMatch the input’s aria-activedescendant waits half a second after the last keystroke.
• The label is a <label for>, so clicking it focuses the input, and it names the list too.

• Combobox is built on it. React Aria’s Autocomplete is inline only, and its ComboBox has keys and a highlight of its own. Here a combo box is an autocomplete in a Popover, so both behave the same.
• The input is a combo box, always expanded, as in Cube UI Kit’s FilterListBox. React Aria’s is a text box or a search box.
• Highlighting the first match is opt-in, with React Aria’s delay before aria-activedescendant. React Aria and Cube UI Kit’s FilterListBox highlight it by default.
• Escape clears the text, then reaches a dialog around the list, as in Cube UI Kit’s FilterListBox and React Aria’s search field. The APG has no list that stays shown: its Escape closes the popup.
• Multiple selection toggles with Enter and a press, and Space types. The APG’s combo box has no keys for it.
• Tab doesn’t choose the highlighted option, as in Combobox. The APG’s example chooses it.