Autocomplete

Previous: Alert DialogNext: Avatar

Suggest text while someone types, without limiting what they can enter.

Use Autocomplete for a text field with helpful suggestions. Choosing one fills in the field, but any text is a valid value. Use Combobox when the value should be a selected option instead.

import "@ui-sdk/web/autocomplete"

const fruits = [
  "Apple",
  "Apricot",
  "Avocado",
  "Banana",
  "Blackberry",
  "Blueberry",
  "Cherry",
  "Grape",
  "Lemon",
  "Mango",
  "Orange",
  "Peach",
  "Pear",
  "Pineapple",
  "Strawberry",
]

function mount(root: HTMLElement) {
  root.innerHTML = `
    <ui-autocomplete>
      <div data-slot="stack">
        <ui-autocomplete-label>Favorite fruit</ui-autocomplete-label>
        <ui-autocomplete-input>
          <input placeholder="e.g. Mango" />
        </ui-autocomplete-input>
      </div>
      <ui-autocomplete-content hidden>
        <ui-autocomplete-empty>No fruits found.</ui-autocomplete-empty>
        <ui-autocomplete-list>
          ${fruits
            .map(
              (fruit) => `
                <ui-autocomplete-item value="${fruit}">${fruit}</ui-autocomplete-item>
              `
            )
            .join("")}
        </ui-autocomplete-list>
      </ui-autocomplete-content>
    </ui-autocomplete>
  `
}

export { mount }
Type “man”, press Down Arrow, then Enter to fill in Mango. You can also leave text that is not in the list.

Installation

npm install @ui-sdk/web @ui-sdk/core

Import the element definitions once in your application:

import "@ui-sdk/web/autocomplete"

Composition

Use the following composition to build a ui-autocomplete:

ui-autocomplete
├── ui-autocomplete-label
├── ui-autocomplete-input
│   └── input
└── ui-autocomplete-content
    ├── ui-autocomplete-empty
    └── ui-autocomplete-list
        ├── ui-autocomplete-item
        └── ui-autocomplete-item

Name the input, then put suggestions in a list inside the popup. ui-autocomplete-input wraps a native input. Each suggestion needs a unique value.

Usage

Import the parts and put them together:

<script type="module">
  import "@ui-sdk/web/autocomplete"
</script>

<ui-autocomplete>
  <ui-autocomplete-label>Fruit</ui-autocomplete-label>
  <ui-autocomplete-input
    ><input placeholder="Type a fruit…"
  /></ui-autocomplete-input>
  <ui-autocomplete-content hidden>
    <ui-autocomplete-list>
      <ui-autocomplete-item value="Apple">Apple</ui-autocomplete-item>
      <ui-autocomplete-item value="Banana">Banana</ui-autocomplete-item>
    </ui-autocomplete-list>
  </ui-autocomplete-content>
</ui-autocomplete>

Autocomplete vs Combobox

Both filter a list as you type. They differ in what the value is.

  • Autocomplete: the value is the text. Suggestions help fill it in, and anything typed is valid. Use it for a search box, an address or a free-form field.
  • Combobox: the value is an option from the list, or several with multiple. The text is only a query; closing without choosing restores the selected label, and a form submits the value, not the text. Use it for a country, an assignee or a set of labels.

Build Your Own

@ui-sdk/web/autocomplete comes with ready-made ui-autocomplete elements. If you'd like to build your own, with your own element names, start from the autocomplete primitive in @ui-sdk/core:

fruit-search-elements.ts
import { autocomplete } from "@ui-sdk/core/autocomplete"
import { createParts, wrappedChild } from "@ui-sdk/web"

createParts(autocomplete, {
  root: "fruit-search",
  label: "fruit-label",
  input: {
    tag: "fruit-input",
    target: wrappedChild("input"),
    display: "contents",
  },
  content: "fruit-popup",
  list: "fruit-list",
  item: "fruit-option",
  empty: "fruit-empty",
})
<fruit-search>
  <fruit-label>Fruit</fruit-label>
  <fruit-input><input /></fruit-input>
  <fruit-popup hidden>
    <fruit-empty>No fruits found.</fruit-empty>
    <fruit-list>
      <fruit-option value="Apple">Apple</fruit-option>
      <fruit-option value="Mango">Mango</fruit-option>
    </fruit-list>
  </fruit-popup>
</fruit-search>

Each element keeps the behavior, state and data attributes of its ready-made counterpart: typing filters the options, arrow keys move the highlight and the popup opens in the top layer. See Rendering and Custom Parts for more.

Disabled

A disabled field cannot be focused or changed and submits nothing. A read-only field stays focusable and submits its value, but does not open or accept changes. Disabled suggestions are skipped by keyboard navigation and cannot fill in the field.

import "@ui-sdk/web/autocomplete"

const fruits = [
  "Apple",
  "Apricot",
  "Avocado",
  "Banana",
  "Blackberry",
  "Blueberry",
  "Cherry",
  "Grape",
  "Lemon",
  "Mango",
  "Orange",
  "Peach",
  "Pear",
  "Pineapple",
  "Strawberry",
]

function mount(root: HTMLElement) {
  root.innerHTML = `
    <div data-slot="stack">
      <ui-autocomplete disabled default-value="Banana">
        <div data-slot="stack">
          <ui-autocomplete-label>Disabled</ui-autocomplete-label>
          <ui-autocomplete-input>
            <input />
          </ui-autocomplete-input>
        </div>
      </ui-autocomplete>
      <ui-autocomplete read-only default-value="Cherry">
        <div data-slot="stack">
          <ui-autocomplete-label>Read-only</ui-autocomplete-label>
          <ui-autocomplete-input>
            <input />
          </ui-autocomplete-input>
        </div>
      </ui-autocomplete>
      <ui-autocomplete>
        <div data-slot="stack">
          <ui-autocomplete-label>Some suggestions disabled</ui-autocomplete-label>
          <ui-autocomplete-input>
            <input placeholder="Type “b”" />
          </ui-autocomplete-input>
        </div>
        <ui-autocomplete-content hidden>
          <ui-autocomplete-list>
            ${fruits
              .map(
                (fruit, index) =>
                  `<ui-autocomplete-item value="${fruit}" ${index % 3 === 0 ? "disabled" : ""}>${fruit}</ui-autocomplete-item>`
              )
              .join("")}
          </ui-autocomplete-list>
        </ui-autocomplete-content>
      </ui-autocomplete>
    </div>
  `
}

export { mount }
Try the Disabled and Read-only fields. In Disabled suggestion, type “b”: arrow keys skip Banana and a press cannot choose it.

Clear and Trigger

ui-autocomplete-clear empties the field and returns focus to it. ui-autocomplete-trigger lets someone open the suggestions without typing. Give the trigger a label that describes what it opens.

import "@ui-sdk/web/autocomplete"
import { ChevronDown, createElement, X } from "lucide"

const fruits = [
  "Apple",
  "Apricot",
  "Avocado",
  "Banana",
  "Blackberry",
  "Blueberry",
  "Cherry",
  "Grape",
  "Lemon",
  "Mango",
  "Orange",
  "Peach",
  "Pear",
  "Pineapple",
  "Strawberry",
]

function mount(root: HTMLElement) {
  root.innerHTML = `
    <ui-autocomplete default-value="Mango">
      <div data-slot="stack">
        <ui-autocomplete-label>Fruit</ui-autocomplete-label>
        <div data-slot="row">
          <ui-autocomplete-input>
            <input />
          </ui-autocomplete-input>
          <ui-autocomplete-clear>
            <button aria-label="Clear">${createElement(X, { "aria-hidden": "true" }).outerHTML}</button>
          </ui-autocomplete-clear>
          <ui-autocomplete-trigger>
            <button aria-label="Show fruits">${createElement(ChevronDown, { "aria-hidden": "true" }).outerHTML}</button>
          </ui-autocomplete-trigger>
        </div>
      </div>
      <ui-autocomplete-content hidden>
        <ui-autocomplete-empty>No fruits found.</ui-autocomplete-empty>
        <ui-autocomplete-list>
          ${fruits.map((fruit) => `<ui-autocomplete-item value="${fruit}">${fruit}</ui-autocomplete-item>`).join("")}
        </ui-autocomplete-list>
      </ui-autocomplete-content>
    </ui-autocomplete>
  `
}

export { mount }
Clear Mango, then press Show fruits to open the suggestions. The clear button disappears while the field is empty.

Open on Focus

Add open-on-focus to offer suggestions as soon as the input receives focus. This works well when there are useful choices before someone types.

import "@ui-sdk/web/autocomplete"

const recent = ["react hooks", "tailwind grid", "web components", "vue v-model"]

function mount(root: HTMLElement) {
  root.innerHTML = `
    <ui-autocomplete open-on-focus>
      <ui-autocomplete-input>
        <input aria-label="Search" placeholder="Search…" />
      </ui-autocomplete-input>
      <ui-autocomplete-content hidden>
        <ui-autocomplete-empty>No results.</ui-autocomplete-empty>
        <ui-autocomplete-list>
          <ui-autocomplete-group>
            <ui-autocomplete-group-label>Recent searches</ui-autocomplete-group-label>
            ${recent.map((search) => `<ui-autocomplete-item value="${search}">${search}</ui-autocomplete-item>`).join("")}
          </ui-autocomplete-group>
        </ui-autocomplete-list>
      </ui-autocomplete-content>
    </ui-autocomplete>
  `
}

export { mount }
Focus Search docs to see recent searches before typing. Escape closes them; pressing the field opens them again.

Auto Highlight

auto-highlight highlights the first match while typing, so Enter can choose it immediately. Set loop to false to stop arrow keys at either end of the list.

import "@ui-sdk/web/autocomplete"

const fruits = [
  "Apple",
  "Apricot",
  "Avocado",
  "Banana",
  "Blackberry",
  "Blueberry",
  "Cherry",
  "Grape",
  "Lemon",
  "Mango",
  "Orange",
  "Peach",
  "Pear",
  "Pineapple",
  "Strawberry",
]

function mount(root: HTMLElement) {
  root.innerHTML = `
    <ui-autocomplete auto-highlight loop="false">
      <div data-slot="stack">
        <ui-autocomplete-label>Fruit</ui-autocomplete-label>
        <ui-autocomplete-input>
          <input placeholder="Type, then Enter" />
        </ui-autocomplete-input>
      </div>
      <ui-autocomplete-content hidden>
        <ui-autocomplete-empty>No fruits found.</ui-autocomplete-empty>
        <ui-autocomplete-list>
          ${fruits.map((fruit) => `<ui-autocomplete-item value="${fruit}">${fruit}</ui-autocomplete-item>`).join("")}
        </ui-autocomplete-list>
      </ui-autocomplete-content>
    </ui-autocomplete>
  `
}

export { mount }
Type “pe” and press Enter to choose the first match. Arrow keys stop at the ends because this example disables looping.

Inline Completion

inline-complete fills in the rest of the first suggestion that starts with the typed text, with the added text selected. Arrow keys fill in the suggestion they highlight. End or Right Arrow accepts the completion; Backspace or Escape takes it back out.

import "@ui-sdk/web/autocomplete"

const fruits = [
  "Apple",
  "Apricot",
  "Avocado",
  "Banana",
  "Blackberry",
  "Blueberry",
  "Cherry",
  "Grape",
  "Lemon",
  "Mango",
  "Orange",
  "Peach",
  "Pear",
  "Pineapple",
  "Strawberry",
]

function mount(root: HTMLElement) {
  root.innerHTML = `
    <ui-autocomplete inline-complete>
      <div data-slot="stack">
        <ui-autocomplete-label>Fruit</ui-autocomplete-label>
        <ui-autocomplete-input>
          <input placeholder="Type “bl”" />
        </ui-autocomplete-input>
      </div>
      <ui-autocomplete-content hidden>
        <ui-autocomplete-empty>No fruits found.</ui-autocomplete-empty>
        <ui-autocomplete-list>
          ${fruits.map((fruit) => `<ui-autocomplete-item value="${fruit}">${fruit}</ui-autocomplete-item>`).join("")}
        </ui-autocomplete-list>
      </ui-autocomplete-content>
    </ui-autocomplete>
  `
}

export { mount }
Type “bl” to complete blackberry inline. Backspace removes the completion; Down Arrow fills in Blueberry. Press End to accept the text.

Highlight Matches

ui-autocomplete-item-text marks the matching text, ignoring case and accents using the current locale. Each match is a <mark> you can style.

import "@ui-sdk/web/autocomplete"

const fruits = [
  "Apple",
  "Apricot",
  "Avocado",
  "Banana",
  "Blackberry",
  "Blueberry",
  "Cherry",
  "Grape",
  "Lemon",
  "Mango",
  "Orange",
  "Peach",
  "Pear",
  "Pineapple",
  "Strawberry",
]

function mount(root: HTMLElement) {
  root.innerHTML = `
    <ui-autocomplete>
      <div data-slot="stack">
        <ui-autocomplete-label>Favorite fruit</ui-autocomplete-label>
        <ui-autocomplete-input>
          <input placeholder="e.g. berry" />
        </ui-autocomplete-input>
      </div>
      <ui-autocomplete-content hidden>
        <ui-autocomplete-empty>No fruits found.</ui-autocomplete-empty>
        <ui-autocomplete-list>
          ${fruits
            .map(
              (fruit) => `
                <ui-autocomplete-item value="${fruit}">
                  <ui-autocomplete-item-text>${fruit}</ui-autocomplete-item-text>
                </ui-autocomplete-item>
              `
            )
            .join("")}
        </ui-autocomplete-list>
      </ui-autocomplete-content>
    </ui-autocomplete>
  `
}

export { mount }
Type “berry”. The matching letters are bold while each suggestion keeps its original spelling.

Filter and Keywords

The default filter matches text anywhere in a suggestion. Use "startsWith" or "fuzzy" for a different match, a function for your own filter, or false for results already filtered by a server. keywords adds searchable text without changing what goes in the field.

import "@ui-sdk/web/autocomplete"

const tags = [
  { value: "feature", label: "feature", keywords: ["enhancement", "request"] },
  { value: "fix", label: "fix", keywords: ["bug", "patch"] },
  { value: "docs", label: "docs", keywords: ["documentation", "readme"] },
  { value: "performance", label: "performance", keywords: ["speed", "slow"] },
  { value: "security", label: "security", keywords: ["vulnerability"] },
  { value: "refactor", label: "refactor", keywords: ["cleanup"] },
]

function mount(root: HTMLElement) {
  root.innerHTML = `
    <ui-autocomplete filter="startsWith">
      <div data-slot="stack">
        <ui-autocomplete-label>Tag</ui-autocomplete-label>
        <ui-autocomplete-input>
          <input placeholder="Try “bug”" />
        </ui-autocomplete-input>
      </div>
      <ui-autocomplete-content hidden>
        <ui-autocomplete-empty>No tags found.</ui-autocomplete-empty>
        <ui-autocomplete-list>
          ${tags
            .map(
              (tag) => `
                <ui-autocomplete-item value="${tag.value}" label="${tag.label}" keywords="${tag.keywords.join(",")}">
                  ${tag.label}
                  <span data-slot="hint">${tag.keywords[0]}</span>
                </ui-autocomplete-item>
              `
            )
            .join("")}
        </ui-autocomplete-list>
      </ui-autocomplete-content>
    </ui-autocomplete>
  `
}

export { mount }
Type “bug” to find fix through its keywords. Type “re” to find labels or keywords that start with those letters.

Groups

Use ui-autocomplete-group and ui-autocomplete-group-label to name related suggestions. Filtering hides empty groups and separators.

import "@ui-sdk/web/autocomplete"

const fruitGroups = [
  {
    label: "Tree fruits",
    items: ["Apple", "Apricot", "Cherry", "Lemon", "Peach", "Pear"],
  },
  {
    label: "Berries",
    items: ["Blackberry", "Blueberry", "Grape", "Strawberry"],
  },
  { label: "Tropical", items: ["Avocado", "Banana", "Mango", "Pineapple"] },
]

function mount(root: HTMLElement) {
  root.innerHTML = `
    <ui-autocomplete>
      <div data-slot="stack">
        <ui-autocomplete-label>Fruit</ui-autocomplete-label>
        <ui-autocomplete-input>
          <input placeholder="e.g. Pear" />
        </ui-autocomplete-input>
      </div>
      <ui-autocomplete-content hidden>
        <ui-autocomplete-empty>No fruits found.</ui-autocomplete-empty>
        <ui-autocomplete-list>
          ${fruitGroups
            .map(
              (group, index) => `
                ${index > 0 ? `<ui-autocomplete-separator></ui-autocomplete-separator>` : ""}
                <ui-autocomplete-group>
                  <ui-autocomplete-group-label>${group.label}</ui-autocomplete-group-label>
                  ${group.items.map((fruit) => `<ui-autocomplete-item value="${fruit}">${fruit}</ui-autocomplete-item>`).join("")}
                </ui-autocomplete-group>
              `
            )
            .join("")}
        </ui-autocomplete-list>
      </ui-autocomplete-content>
    </ui-autocomplete>
  `
}

export { mount }
Type “an”. Banana and Mango remain in Tropical; groups with no matches disappear.

Icons

ui-autocomplete-item-icon keeps decorative icons out of accessible names, filtering, and the text put in the field. Add mirror for directional icons. An icon-only suggestion still needs an aria-label.

import "@ui-sdk/web/autocomplete"
import {
  Archive,
  Clock,
  createElement,
  File,
  Pencil,
  Reply,
  Star,
} from "lucide"

const mailSearches = [
  { value: "Starred", icon: Star },
  { value: "Drafts", icon: Pencil },
  { value: "Replies", icon: Reply, mirror: true },
  { value: "Attachments", icon: File },
  { value: "Archived", icon: Archive },
  { value: "Scheduled", icon: Clock },
]

function mount(root: HTMLElement) {
  root.innerHTML = `
    <ui-autocomplete>
      <ui-autocomplete-input>
        <input type="search" aria-label="Search mail" placeholder="Search mail…" />
      </ui-autocomplete-input>
      <ui-autocomplete-content hidden>
        <ui-autocomplete-empty>No searches found.</ui-autocomplete-empty>
        <ui-autocomplete-list>
          ${mailSearches
            .map(
              (search) => `
                <ui-autocomplete-item value="${search.value}"><ui-autocomplete-item-icon ${search.mirror ? "mirror" : ""}>${createElement(search.icon, { "aria-hidden": "true" }).outerHTML}</ui-autocomplete-item-icon>${search.value}</ui-autocomplete-item>
              `
            )
            .join("")}
        </ui-autocomplete-list>
      </ui-autocomplete-content>
    </ui-autocomplete>
  `
}

export { mount }
Type “rep” and choose Replies. The icon stays out of the text put in the field.

Items as Data

Map an array into parts when you want to write the markup yourself. This example maps fruit groups and adds a separator between them.

import "@ui-sdk/web/autocomplete"

const fruitGroups = [
  {
    label: "Tree fruits",
    fruits: ["Apple", "Apricot", "Cherry", "Lemon", "Peach", "Pear"],
  },
  {
    label: "Berries",
    fruits: ["Blackberry", "Blueberry", "Grape", "Strawberry"],
  },
  { label: "Tropical", fruits: ["Avocado", "Banana", "Mango", "Pineapple"] },
]

function mount(root: HTMLElement) {
  root.innerHTML = `
    <ui-autocomplete>
      <div data-slot="stack">
        <ui-autocomplete-label>Fruit</ui-autocomplete-label>
        <ui-autocomplete-input>
          <input placeholder="e.g. Peach" />
        </ui-autocomplete-input>
      </div>
      <ui-autocomplete-content hidden>
        <ui-autocomplete-empty>No fruits found.</ui-autocomplete-empty>
        <ui-autocomplete-list>
          ${fruitGroups
            .map(
              (group, index) => `
                ${index > 0 ? `<ui-autocomplete-separator></ui-autocomplete-separator>` : ""}
                <ui-autocomplete-group>
                  <ui-autocomplete-group-label>${group.label}</ui-autocomplete-group-label>
                  ${group.fruits.map((fruit) => `<ui-autocomplete-item value="${fruit}">${fruit}</ui-autocomplete-item>`).join("")}
                </ui-autocomplete-group>
              `
            )
            .join("")}
        </ui-autocomplete-list>
      </ui-autocomplete-content>
    </ui-autocomplete>
  `
}

export { mount }
Open the list to see three fruit groups. Type “an” to narrow them to Banana and Mango.

Pass items when the autocomplete needs the whole collection, such as server results or recent searches. Assign it as a property and use a <template> to style the generated parts. Lists and Menus covers the ListData format.

Suggestions can change while the list is open. The highlight stays with its suggestion, and the typed text stays unchanged. Removing the highlighted suggestion clears the highlight.

Controlled

The value is always a string. Set its initial text with default-value, then read or write the element’s value property. The popup has a separate open property. Listen for valuechange and openchange; the requested value is in event.detail.value. Call event.preventDefault() to reject a change. State and Events covers controlled state and cancellation.

Console
import "@ui-sdk/web/autocomplete"
import { log } from "./log"

const fruits = [
  "Apple",
  "Apricot",
  "Avocado",
  "Banana",
  "Blackberry",
  "Blueberry",
  "Cherry",
  "Grape",
  "Lemon",
  "Mango",
  "Orange",
  "Peach",
  "Pear",
  "Pineapple",
  "Strawberry",
]

function mount(root: HTMLElement) {
  root.innerHTML = `
    <div data-slot="stack">
      <ui-autocomplete debug>
        <ui-autocomplete-label>Fruit (12 characters at most)</ui-autocomplete-label>
        <ui-autocomplete-input>
          <input />
        </ui-autocomplete-input>
        <ui-autocomplete-content hidden>
          <ui-autocomplete-empty>No fruits found.</ui-autocomplete-empty>
          <ui-autocomplete-list>
            ${fruits.map((fruit) => `<ui-autocomplete-item value="${fruit}">${fruit}</ui-autocomplete-item>`).join("")}
          </ui-autocomplete-list>
        </ui-autocomplete-content>
      </ui-autocomplete>
    </div>
  `
  const autocomplete = root.querySelector("ui-autocomplete")!
  autocomplete.addEventListener("valuechange", (event) => {
    if (event.detail.value.length > 12) {
      return event.preventDefault()
    }
    log(root, `text: ${event.detail.reason}`)
  })
  autocomplete.addEventListener("openchange", (event) => {
    log(
      root,
      `${event.detail.value ? "opened" : "closed"}: ${event.detail.reason}`
    )
  })
  autocomplete.addEventListener("openchangecomplete", (event) => {
    log(root, `${event.detail.value ? "opened" : "closed"} and settled`)
  })
  autocomplete.addEventListener("highlight", (event) => {
    if (event.detail.value) {
      log(root, `highlighted ${event.detail.value}`)
    }
  })
}

export { mount }
Type more than 12 characters and the extra text is refused. The console shows each change and its reason.

Controller

Use the element’s api property. It can setValue(), clear(), focus(), setOpen(), or read getValue() and isOpen(). open() returns a promise that resolves when the popup closes, including abort and unmount; close() closes it. See Controllers for lifecycle and change options.

import "@ui-sdk/web/autocomplete"

const fruits = [
  "Apple",
  "Apricot",
  "Avocado",
  "Banana",
  "Blackberry",
  "Blueberry",
  "Cherry",
  "Grape",
  "Lemon",
  "Mango",
  "Orange",
  "Peach",
  "Pear",
  "Pineapple",
  "Strawberry",
]

function mount(root: HTMLElement) {
  root.innerHTML = `
    <div data-slot="stack">
      <div data-slot="controls">
        <button type="button" data-action="open" data-size="sm">Open</button>
        <button type="button" data-action="type" data-size="sm">Type “Pea”</button>
        <button type="button" data-action="clear" data-size="sm">Clear</button>
        <button type="button" data-action="focus" data-size="sm">Focus</button>
      </div>
      <ui-autocomplete>
        <ui-autocomplete-label>Fruit</ui-autocomplete-label>
        <ui-autocomplete-input>
          <input />
        </ui-autocomplete-input>
        <ui-autocomplete-content hidden>
          <ui-autocomplete-empty>No fruits found.</ui-autocomplete-empty>
          <ui-autocomplete-list>
            ${fruits.map((item) => `<ui-autocomplete-item value="${item}">${item}</ui-autocomplete-item>`).join("")}
          </ui-autocomplete-list>
        </ui-autocomplete-content>
      </ui-autocomplete>
    </div>
  `
  const fruit = root.querySelector("ui-autocomplete")!.api
  const actions: Record<string, () => void> = {
    open: () => fruit.open(),
    type: () => fruit.setValue("Pea"),
    clear: () => fruit.clear(),
    focus: () => fruit.focus(),
  }
  for (const button of root.querySelectorAll<HTMLElement>("[data-action]")) {
    button.addEventListener("click", () => actions[button.dataset.action!]())
  }
}

export { mount }
Use the buttons to open the suggestions, type Pea, clear the field or focus it from outside.

Positioning

Use side, align, offsets, or a custom anchor to position the suggestions. container chooses where they render, and keep-mounted keeps closed content in the DOM. Popups covers positioning, portals, animation, and modal behavior.

import "@ui-sdk/web/autocomplete"

const fruits = [
  "Apple",
  "Apricot",
  "Avocado",
  "Banana",
  "Blackberry",
  "Blueberry",
]

function mount(root: HTMLElement) {
  root.innerHTML = `
    <div id="autocomplete-positioning-box" data-slot="card">
      <ui-autocomplete modal="pointer" container="#autocomplete-positioning-box">
        <div data-slot="stack">
          <ui-autocomplete-label>Fruit</ui-autocomplete-label>
          <ui-autocomplete-input>
            <input />
          </ui-autocomplete-input>
        </div>
        <ui-autocomplete-content side="top" align="end" side-offset="10" align-offset="-4" collision-padding="8" anchor="#autocomplete-positioning-box" keep-mounted hidden>
          <ui-autocomplete-empty>No fruits found.</ui-autocomplete-empty>
          <ui-autocomplete-list>
            ${fruits.map((fruit) => `<ui-autocomplete-item value="${fruit}">${fruit}</ui-autocomplete-item>`).join("")}
          </ui-autocomplete-list>
        </ui-autocomplete-content>
      </ui-autocomplete>
    </div>
  `
}

export { mount }
Open the suggestions. They appear above the card, aligned to its end.

Animation

The content has data-starting-style while it opens and data-ending-style while it closes. Transition from those states, and the popup stays mounted until the exit finishes:

[data-slot="autocomplete-content"] {
  transition:
    opacity 0.15s,
    translate 0.2s cubic-bezier(0.22, 1, 0.36, 1);

  &:is([data-starting-style], [data-ending-style]) {
    opacity: 0;
    translate: 0 -6px;
  }
}
import "@ui-sdk/web/autocomplete"

const fruits = [
  "Apple",
  "Apricot",
  "Avocado",
  "Banana",
  "Blackberry",
  "Blueberry",
  "Cherry",
  "Grape",
  "Lemon",
  "Mango",
  "Orange",
  "Peach",
  "Pear",
  "Pineapple",
  "Strawberry",
]

function mount(root: HTMLElement) {
  root.innerHTML = `
    <ui-autocomplete>
      <div data-slot="stack">
        <ui-autocomplete-label>Favorite fruit</ui-autocomplete-label>
        <ui-autocomplete-input>
          <input placeholder="e.g. Mango" />
        </ui-autocomplete-input>
      </div>
      <ui-autocomplete-content hidden>
        <ui-autocomplete-empty>No fruits found.</ui-autocomplete-empty>
        <ui-autocomplete-list>
          ${fruits
            .map(
              (fruit) => `
                <ui-autocomplete-item value="${fruit}">${fruit}</ui-autocomplete-item>
              `
            )
            .join("")}
        </ui-autocomplete-list>
      </ui-autocomplete-content>
    </ui-autocomplete>
  `
}

export { mount }
Type to open the suggestions. They slide and fade in, and fade out before they unmount.

Presentation

presentation="sheet" opens suggestions in a sheet. "auto" chooses a sheet on small touch screens and a popover elsewhere, each time the list opens. The server starts with the popover.

The same input moves into the sheet’s header. Opening by touch leaves the keyboard closed; tapping the input opens it and expands the sheet. Choosing a suggestion or swiping down closes it. Keyboard and mouse opening preserve input focus.

A sheet is modal unless modal is false. Give it a height, keep suggestions inside ui-autocomplete-list, and leave the content’s translate alone so dragging can move it. Use data-presentation to style both presentations and --sheet-backdrop to set the dimmed background.

import "@ui-sdk/web/autocomplete"

const fruits = [
  "Apple",
  "Apricot",
  "Avocado",
  "Banana",
  "Blackberry",
  "Blueberry",
  "Cherry",
  "Grape",
  "Lemon",
  "Mango",
  "Orange",
  "Peach",
  "Pear",
  "Pineapple",
  "Strawberry",
]

function mount(root: HTMLElement) {
  root.innerHTML = `
    <ui-autocomplete presentation="sheet">
      <div data-slot="stack">
        <ui-autocomplete-label>Favorite fruit</ui-autocomplete-label>
        <ui-autocomplete-input>
          <input placeholder="e.g. Mango" />
        </ui-autocomplete-input>
      </div>
      <ui-autocomplete-content hidden>
        <ui-autocomplete-empty>No fruits found.</ui-autocomplete-empty>
        <ui-autocomplete-list>
          ${fruits.map((fruit) => `<ui-autocomplete-item value="${fruit}">${fruit}</ui-autocomplete-item>`).join("")}
        </ui-autocomplete-list>
      </ui-autocomplete-content>
    </ui-autocomplete>
  `
}

export { mount }
Open the field to see a sheet. On touch, tap the field in its header to show the keyboard, or swipe down to close it.

Forms

The native input is the form control: name gives its submitted key, required rejects empty text, and reset restores default-value. Text does not have to match a suggestion. Use form to associate the field with a form elsewhere in the page.

Console
import "@ui-sdk/web/autocomplete"
import "@ui-sdk/web/field"
import { log } from "./log"

const fruits = [
  "Apple",
  "Apricot",
  "Avocado",
  "Banana",
  "Blackberry",
  "Blueberry",
  "Cherry",
  "Grape",
  "Lemon",
  "Mango",
  "Orange",
  "Peach",
  "Pear",
  "Pineapple",
  "Strawberry",
]

function mount(root: HTMLElement) {
  root.innerHTML = `
    <form id="order" data-slot="stack">
      <ui-field>
        <ui-field-label>Fruit</ui-field-label>
        <ui-autocomplete name="fruit" form="order" required default-value="Apple">
          <ui-autocomplete-input>
            <input />
          </ui-autocomplete-input>
          <ui-autocomplete-content hidden>
            <ui-autocomplete-empty>No fruits found.</ui-autocomplete-empty>
            <ui-autocomplete-list>
              ${fruits.map((fruit) => `<ui-autocomplete-item value="${fruit}">${fruit}</ui-autocomplete-item>`).join("")}
            </ui-autocomplete-list>
          </ui-autocomplete-content>
        </ui-autocomplete>
        <ui-field-description>Any fruit, listed or not.</ui-field-description>
        <div><ui-field-error></ui-field-error></div>
      </ui-field>
      <div data-slot="row">
        <button type="submit" data-variant="solid">Submit</button>
        <button type="reset">Reset</button>
      </div>
    </form>
  `
  const form = root.querySelector("form")!
  form.addEventListener("submit", (event) => {
    event.preventDefault()
    const data = [...new FormData(form)].map(
      ([name, value]) => `${name}=${value}`
    )
    log(root, `Submitted ${data.join("&")}`)
  })
}

export { mount }
Submit Apple, then choose Mango. Choosing it fills the field without submitting. Reset restores Apple.

Search

Enter with no suggestion highlighted fires a submit event with the text, then allows the surrounding form to submit. Call preventDefault() on the submit event if your handler already performs the search.

Choosing a suggestion normally only fills in the field. Add submit-on-select to search as soon as someone chooses one.

Console
import "@ui-sdk/web/autocomplete"
import { log } from "./log"

const recent = ["react hooks", "tailwind grid", "web components", "vue v-model"]

function mount(root: HTMLElement) {
  root.innerHTML = `
    <form role="search" data-slot="stack">
      <ui-autocomplete submit-on-select name="q">
        <ui-autocomplete-input>
          <input type="search" aria-label="Search" placeholder="Search…" />
        </ui-autocomplete-input>
        <ui-autocomplete-content hidden>
          <ui-autocomplete-empty>No results.</ui-autocomplete-empty>
          <ui-autocomplete-list>
            ${recent.map((search) => `<ui-autocomplete-item value="${search}">${search}</ui-autocomplete-item>`).join("")}
          </ui-autocomplete-list>
        </ui-autocomplete-content>
      </ui-autocomplete>
    </form>
  `
  root
    .querySelector("form")!
    .addEventListener("submit", (event) => event.preventDefault())
  root.querySelector("ui-autocomplete")!.addEventListener("submit", (event) => {
    log(root, `Searched “${event.detail.value}”`)
  })
}

export { mount }
Type “kotlin” and press Enter to search. Choose a suggestion to search for that text instead.

Recent Searches

Pair emptyItems with items to show one collection while the field is empty and search the full collection once someone types. Add open-on-focus to show the recent searches on focus.

import "@ui-sdk/web/autocomplete"

const recent = ["react hooks", "tailwind grid", "web components", "vue v-model"]
const topics = [
  ...recent,
  "react server components",
  "tailwind colors",
  "vue router",
]
const recentSearches = [
  { type: "group" as const, label: "Recent searches", items: recent },
]

function mount(root: HTMLElement) {
  root.innerHTML = `
    <ui-autocomplete open-on-focus>
      <ui-autocomplete-input>
        <input type="search" aria-label="Search docs" placeholder="Search docs…" />
      </ui-autocomplete-input>
      <ui-autocomplete-content hidden>
        <ui-autocomplete-empty>No topics found.</ui-autocomplete-empty>
        <ui-autocomplete-list></ui-autocomplete-list>
      </ui-autocomplete-content>
      <template>
        <ui-autocomplete-group>
          <ui-autocomplete-group-label></ui-autocomplete-group-label>
          <ui-autocomplete-item>
            <ui-autocomplete-item-text></ui-autocomplete-item-text>
          </ui-autocomplete-item>
        </ui-autocomplete-group>
      </template>
    </ui-autocomplete>
  `
  const autocomplete = root.querySelector("ui-autocomplete")!
  autocomplete.announcement = (change) =>
    change.type === "results"
      ? `${change.count} ${change.count === 1 ? "topic" : "topics"}`
      : null
  autocomplete.emptyItems = recentSearches
  autocomplete.items = topics
}

export { mount }
Focus the empty field to see Recent searches. Type “react” to search all topics, then clear the text to return to recent searches.

Async Suggestions

Use async options to wait for typing to pause and discard stale results. Pass its items and status, set filter to false, and send text changes to its setQuery() method.

ui-autocomplete-status and ui-autocomplete-empty provide loading, error, and empty messages. Without a status part, announcement controls what screen readers hear when typing pauses. The loadmore event can request another page when scrolling or highlighting reaches the last suggestion.

import { createAsyncOptions } from "@ui-sdk/core/async-options"
import "@ui-sdk/web/autocomplete"

function searchCities(query: string, { signal }: { signal: AbortSignal }) {
  const cities = [
    "Amsterdam",
    "Athens",
    "Barcelona",
    "Berlin",
    "Boston",
    "Brussels",
    "Buenos Aires",
    "Cairo",
    "Chicago",
    "Copenhagen",
    "Dublin",
    "Lisbon",
    "London",
    "Los Angeles",
    "Madrid",
    "Paris",
    "Prague",
    "Rome",
    "Seoul",
    "Tokyo",
  ]
  return new Promise<string[]>((resolve, reject) => {
    const timer = setTimeout(() => {
      const needle = query.trim().toLowerCase()
      resolve(cities.filter((city) => city.toLowerCase().startsWith(needle)))
    }, 300)
    signal.addEventListener("abort", () => {
      clearTimeout(timer)
      reject(new DOMException("Aborted", "AbortError"))
    })
  })
}

function mount(root: HTMLElement) {
  root.innerHTML = `
    <ui-autocomplete filter="false">
      <div data-slot="stack">
        <ui-autocomplete-label>City</ui-autocomplete-label>
        <ui-autocomplete-input>
          <input placeholder="e.g. Paris" />
        </ui-autocomplete-input>
      </div>
      <ui-autocomplete-content hidden>
        <ui-autocomplete-status></ui-autocomplete-status>
        <ui-autocomplete-empty>No cities start with “<span></span>”.</ui-autocomplete-empty>
        <ui-autocomplete-list></ui-autocomplete-list>
      </ui-autocomplete-content>
      <template>
        <ui-autocomplete-item>
        </ui-autocomplete-item>
      </template>
    </ui-autocomplete>
  `
  const autocomplete = root.querySelector("ui-autocomplete")!
  const status = root.querySelector("ui-autocomplete-status")!
  const query = root.querySelector("ui-autocomplete-empty span")!
  const results = createAsyncOptions(searchCities, { debounce: 200 })
  const update = () => {
    const { items, status: loading } = results.getState()
    autocomplete.items = items
    autocomplete.setAttribute("status", loading)
    status.textContent =
      loading === "loading"
        ? "Searching…"
        : items.length
          ? `${items.length} ${items.length === 1 ? "city" : "cities"}`
          : ""
  }
  results.subscribe(update)
  update()
  autocomplete.addEventListener("valuechange", (event) => {
    query.textContent = event.detail.value
    results.setQuery(event.detail.value)
  })
  autocomplete.addEventListener("loadmore", () => results.loadMore())
}

export { mount }
Type “b” and wait for the city suggestions. Keep typing to replace the search; the status describes the latest results.

Custom Rendering

Add as-child to give a suggestion a different element: the suggestion binds the element inside it. Here each suggestion is a link, so the autocomplete works as a jump-to menu: Enter or a click follows the highlighted link, and the text after the title is a hint that doesn't affect filtering. Parts and Composition covers the element wrapping API.

import "@ui-sdk/web/autocomplete"

const pages = [
  { title: "Installation", section: "Get Started", href: "#installation" },
  { title: "Composition", section: "Concepts", href: "#composition" },
  { title: "Build Your Own", section: "Concepts", href: "#build-your-own" },
  { title: "Styling", section: "Guides", href: "#styling" },
  { title: "API Reference", section: "Reference", href: "#api-reference" },
  { title: "Accessibility", section: "Reference", href: "#accessibility" },
]

function mount(root: HTMLElement) {
  root.innerHTML = `
    <ui-autocomplete>
      <div data-slot="stack">
        <ui-autocomplete-label>Jump to</ui-autocomplete-label>
        <ui-autocomplete-input>
          <input placeholder="e.g. Styling" />
        </ui-autocomplete-input>
      </div>
      <ui-autocomplete-content hidden>
        <ui-autocomplete-empty>No sections found.</ui-autocomplete-empty>
        <ui-autocomplete-list>
          ${pages
            .map(
              (page) => `
                <ui-autocomplete-item value="${page.title}" label="${page.title}" as-child>
                  <a href="${page.href}">${page.title}<span data-slot="hint">${page.section}</span></a>
                </ui-autocomplete-item>
              `
            )
            .join("")}
        </ui-autocomplete-list>
      </ui-autocomplete-content>
    </ui-autocomplete>
  `
}

export { mount }
Type “sty” and press Enter to jump to the Styling section of this page.

Styling

Each element has a data-slot, such as autocomplete-content, and shows its state through the attributes listed under Data Attributes.

The popup exposes sizing and animation variables. --anchor-width is the input’s width; use --available-height on the content to keep a long list in the viewport.

While focus stays in the input, use the content’s data-modality="keyboard" with an item’s data-highlighted to show a keyboard focus indicator on the highlighted suggestion.

<ui-autocomplete-content>

VariableWhat it holds
--anchor-widthWidth of the anchor, usually the trigger. Use it to match widths.
--anchor-heightHeight of the anchor.
--available-widthSpace beside the popup, up to the viewport edge. Not inherited either.
--available-heightSpace between the anchor and the viewport edge. Use it for max-height. Not inherited, so a child that needs it copies it on the popup, like [--list-height:var(--available-height)], and reads max-h-(--list-height). The first popup registers both names for the whole page with CSS.registerProperty, so they don't inherit anywhere. A page that needs them to inherit calls it first, with inherits: true. An @property rule can't, since a registration in script wins.
--transform-originThe point on the anchor the popup opens from. Use it to scale from the right place.
--arrow-offsetWhere the anchor's center falls along the popup's edge, kept arrowPadding from the corners. Position a ::before arrow with it.
--drawer-progressWhile it presents as a sheet: how far open the sheet is, from 0 closed to 1 at its largest snap point. Never past 1.
--drawer-dimWhile it presents as a sheet: how dim the page behind is, from 0 to 1. The backdrop's opacity follows it.
--drawer-expandWhile it presents as a sheet: 0 at the second-largest snap point and below, 1 at the largest. With one snap point, the whole travel.
--drawer-stackWhile it presents as a sheet: how many sheets opened from inside this one are open above it, rising smoothly as each one opens. Push it back with it.
--sheet-backdropSet it yourself: the color the page dims to while it presents as a sheet. Black at 0.2 by default.

<ui-autocomplete-viewport>

VariableWhat it holds
--keyboard-insetWhile it presents as a sheet: how many pixels of the page the on-screen keyboard covers, 0 without one.
--visual-viewport-widthWhile it presents as a sheet: the width of the part of the page you can see.
--visual-viewport-heightWhile it presents as a sheet: the height of the part of the page you can see, above the keyboard.
--visual-viewport-topWhile it presents as a sheet: how far the part of the page you can see is scrolled from the top of the layout, as when the keyboard pushes it up.

Data Attributes

<ui-autocomplete-label>

[data-slot="autocomplete-label"]

AttributeWhat it means
data-disabledPresent when the field is disabled, by its own prop, a field or a <fieldset>.
data-readonlyPresent when the field is read-only.
data-requiredPresent when the field is required.

<ui-autocomplete-input>

[data-slot="autocomplete-input"]

AttributeWhat it means
data-closedPresent while the suggestions are closed, including while they animate out.
data-openPresent while the suggestions are open.
data-disabledPresent when the field is disabled, by its own prop, a field or a <fieldset>.
data-readonlyPresent when the field is read-only.
data-requiredPresent when the field is required.

<ui-autocomplete-trigger>

[data-slot="autocomplete-trigger"]

AttributeWhat it means
data-closedPresent while the suggestions are closed, including while they animate out.
data-openPresent while the suggestions are open.
data-disabledPresent when the field is disabled, by its own prop, a field or a <fieldset>.
data-readonlyPresent when the field is read-only.
data-requiredPresent when the field is required.

<ui-autocomplete-clear>

[data-slot="autocomplete-clear"]

AttributeWhat it means
data-disabledPresent when the field is disabled or read-only.

<ui-autocomplete-content>

[data-slot="autocomplete-content"]

AttributeWhat it means
data-closedPresent while the suggestions are closed, including while they animate out.
data-presentationpopoversheetHow the suggestions present this time they're open.
data-openPresent while the suggestions are open.
data-starting-stylePresent for the first frame. Style the state you animate from.
data-ending-stylePresent while the list animates out. Style the state you animate to.
data-modalitykeyboardpointerWhether the keyboard or a pointer moves the highlight. Style a focus ring for the keyboard only.
data-has-iconsPresent while any suggestion inside holds an icon part, so items without one can line up.

<ui-autocomplete-item>

[data-slot="autocomplete-item"]

AttributeWhat it means
data-disabledPresent when the suggestion can't be chosen. Arrow keys skip it.
data-highlightedPresent on the highlighted suggestion, which Enter fills in. Focus stays in the field.
data-has-iconPresent on a suggestion while it holds an icon part.

<ui-autocomplete-item-text>

[data-slot="autocomplete-item-text"]

AttributeWhat it means
data-matchedPresent on a suggestion's text while the field's text matched part of it, which is marked.

<ui-autocomplete-empty>

[data-slot="autocomplete-empty"]

AttributeWhat it means
data-loadingPresent while results load, with status="loading".
data-emptyPresent while no suggestion matches.

<ui-autocomplete-status>

[data-slot="autocomplete-status"]

AttributeWhat it means
data-loadingPresent while results load, with status="loading".

<ui-autocomplete-arrow>

[data-slot="autocomplete-arrow"]

AttributeWhat it means
data-closedPresent while the suggestions are closed, including while they animate out.
data-openPresent while the suggestions are open.

<ui-autocomplete-item-icon>

[data-slot="autocomplete-item-icon"]

AttributeWhat it means
data-mirrorPresent on an icon that flips in right-to-left text, with mirror.

API Reference

Props are attributes in kebab case, like default-value, inline-complete and open-on-focus. filter takes contains, startsWith, fuzzy or false. items and a filter function are properties. container and anchor take CSS selectors. Callbacks are DOM events.

Autocomplete

container?DocumentFragment | Element | null
Renders the popup into this element instead of in place, like a container inside a shadow root or an iframe. On web components, a CSS selector. Nested popups stay inside their parent.
value?string
The text. Pass it to control it.
defaultValue?string
The text at first, when uncontrolled. A form reset returns to it.
valuechange event
Runs when the text wants to change: typing, choosing a suggestion, a Clear part, a form reset or a controller. details.cancel() keeps it as it was.
open?boolean
Whether the suggestions are open. Pass it to control them.
defaultOpen?boolean
Whether the suggestions start open, when uncontrolled.
openchange event
Runs when the suggestions want to open or close. details.reason says why, and details.cancel() stops it.
openchangecomplete event
Runs once the suggestions have finished opening or closing, after any animation.
submit event
Runs with the text when Enter is pressed with no suggestion highlighted, or after choosing one with submitOnSelect. The surrounding form submits next, unless the event's preventDefault() is called.
items?ListData<string>
The suggestions as data. Renders them for you, and filters them without rendering every one.
emptyItems?ListData<string>
Suggestions shown instead of items while the field is empty, like recent searches, with openOnFocus. Groups work, like { type: "group", label: "Recent", items }. Needs items.
filter?SearchFilter<string>
How typing narrows the suggestions: "contains", "startsWith", "fuzzy", a function of the item and the text, or false to keep every one, for results a server already filtered.
inlineComplete?boolean
Whether typing completes the text with the first suggestion that starts with it, with the rest selected after the caret: ArrowRight or End accepts it, Backspace and Escape take it back out, and arrow keys fill in the suggestion they highlight.
autoHighlight?boolean
Whether the first suggestion is highlighted while typing, so Enter chooses it.
openOnFocus?boolean
Whether the suggestions open when the field gets focus, like recent searches, even before anything is typed.
submitOnSelect?boolean
Whether choosing a suggestion submits, like a search box: submit runs, then the form submits.
status?AsyncOptionsStatus
Whether results are loading or failed, for the empty and status parts. Sets aria-busy on the list while loading.
highlight event
Runs when the highlight moves, with the suggestion's index among the visible ones, so a virtualized list can scroll to it.
loadmore event
Runs when the highlight or scrolling reaches the last suggestion, so the next page can load, like createAsyncOptions's loadMore. Not again for the same suggestions, unless the last load failed.
announcement?((change: ListAnnouncement) => string | null | undefined)
What screen readers hear after typing pauses, when no AutocompleteStatus is rendered. Return null for nothing.
loop?boolean
Whether arrow keys wrap from the last suggestion to the first.
modal?"pointer" | boolean
false: the page stays usable while the suggestions are open. "pointer": an outside press only closes them. true: also locks scroll and makes the rest of the page inert.
presentation?PresentationSetting<"popover">
How the suggestions present. "sheet" slides them up from the bottom of the screen with the field in its header, where they can be swiped away, and "auto" does that on small touch screens. A tap that opens a sheet leaves the keyboard closed until the field in the header is tapped. Decided each time they open; the server renders "popover" for "auto".
disabled?boolean
Disables the field like a native input: it can't be focused or changed, and its text isn't submitted.
readOnly?boolean
Keeps the field focusable and its text submitted, but stops changes.
required?boolean
Blocks form submission while the field is empty, with the browser's own message.
name?string
The name the text submits under.
form?string
The id of a form to belong to, when the field isn't inside that form.
controller?object
Opens, closes, reads and sets the autocomplete from anywhere. Create one with createAutocompleteController().
dismissible?boolean
Whether Escape, an outside press, focus or the window leaving, Android's back gesture and a sheet's swipe can close it. Triggers, Close parts and the controller always can. Pass false while it holds unsaved work, and ask in dismissattempt.
dismissattempt event
Runs when dismissible refused a dismissal made on purpose: Escape, an outside press, back or a swipe. Focus or the window leaving is refused without it. Ask "Discard changes?" here.
debug?boolean
Logs every state change with its reason to the console, in development builds.

AutocompleteLabel

Names the input. <ui-autocomplete-label> labels the input, so you don't need a ui-field.

AutocompleteInput

The text field. <ui-autocomplete-input> wraps a native input and gives it the combobox role.

AutocompleteTrigger

An optional button that opens and closes the suggestions. <ui-autocomplete-trigger> wraps a native button.

AutocompleteClear

keepMounted?boolean
Whether the clear button stays in the page while the field is empty.

AutocompleteContent

side?Side
Which side of the anchor the popup opens on. Flips to the other side when there isn't room. Which side of the field the suggestions open on.
align?Align
How the popup lines up with the anchor along that side. start and end follow the reading direction. How the suggestions line up with the field along that side.
sideOffset?number
Gap between the anchor and the popup, in pixels. Gap between the field and the suggestions, in pixels.
alignOffset?number
Shift along the anchor, in pixels. Shift along the field, in pixels.
collisionPadding?number
Space to keep from the viewport edges, in pixels.
arrowPadding?number
Space to keep between the arrow and the popup's corners, in pixels.
anchor?string | Anchor | null
Positions the popup against this instead of its trigger: an element, a CSS selector, a point like { x, y }, or anything with getBoundingClientRect(). It's read on every check, so it can move. A controller's open({ anchor }) wins for that open.
container?DocumentFragment | Element | null
Renders the popup into this element instead of in place, like a container inside a shadow root or an iframe. On web components, a CSS selector. Nested popups stay inside their parent.
keepMounted?boolean
Whether the suggestions stay in the page, hidden, while closed.

AutocompleteArrow

An optional arrow pointing at the input. <ui-autocomplete-arrow> is positioned on the content's edge.

AutocompleteStatus

Announces loading and result counts to screen readers. <ui-autocomplete-status> announces the text you put in it.

AutocompleteEmpty

Shows when no suggestion matches. <ui-autocomplete-empty> stays hidden while there are matches.

AutocompleteList

Holds the suggestions. <ui-autocomplete-list> is the listbox, and renders items when you set them.

AutocompleteGroup

Groups related suggestions. <ui-autocomplete-group> has the group role.

AutocompleteGroupLabel

Names its group. <ui-autocomplete-group-label> labels the group.

AutocompleteItem

valuestring
Identifies the suggestion. Choosing it fills the field with its label, or with this when there's none.
label?string
The text the field gets and filtering matches, when the content isn't plain text. Not the accessible name: use aria-label for that.
keywords?string[]
More words filtering matches.
disabled?boolean
Keeps the suggestion from being chosen. Sets data-disabled and aria-disabled.
index?number
The suggestion's position among all visible ones, for virtualized lists that render only some. Sets aria-posinset and aria-setsize.

AutocompleteItemIcon

mirror?boolean
Flips the icon horizontally in right-to-left text, for icons that point a way, like arrows and chevrons. Icons that picture a thing, like a clock or a check, stay as they are.

AutocompleteItemText

The suggestion's text, with the matched part in <mark>. <ui-autocomplete-item-text> holds text only.

AutocompleteSeparator

A divider between suggestions or groups. <ui-autocomplete-separator> has the separator role.

Items as Data

Each suggestion in items, or a plain string. Groups are { type: "group", label, items } and separators { type: "separator" }.

valueT
Identifies the item, and is what choosing it reports. A string, or any value with itemToValue.
labelstring
The text shown and matched by typeahead and filtering. A select's trigger shows it once chosen.
keywords?string[]
More words filtering matches, like ["team"] for a plan called Pro.
disabled?boolean
Keeps the item from being chosen. The keyboard skips it, like in a native select.

The whole array is a ListData.

State

The same state shows as data attributes on each element.

AutocompleteInput and AutocompleteTrigger:

openboolean
Whether the suggestions are open.
disabledboolean
Whether the field is disabled, by itself or by a <fieldset>.
readOnlyboolean
Whether the field is read-only.
requiredboolean
Whether the field is required.

AutocompleteContent and AutocompleteList:

openboolean
Whether the suggestions are open. False while they animate out.
presentation"popover" | "sheet"
How they present this time they're open.
statusAsyncOptionsStatus
Whether results are loading or failed.
itemsListData<string>
The visible suggestions, for rendering a virtualized list yourself.

AutocompleteItem:

highlightedboolean
Whether the suggestion is highlighted, by the keyboard or the pointer.
disabledboolean
Whether the suggestion can't be chosen.

AutocompleteEmpty:

loadingboolean
Whether results are loading.
emptyboolean
Whether no item matches.
querystring
The text the list is filtered by.

AutocompleteStatus:

status"idle" | "loading" | "error"
Whether results are loading or failed.
loadingboolean
Whether results are loading.
countnumber
How many items are visible.

AutocompleteClear:

disabledboolean
Whether the field is disabled or read-only.

AutocompleteArrow:

openboolean
Whether the suggestions are open.

AutocompleteItemText, which takes no props of its own:

segmentsMatchSegment[]
The text in pieces, each marked when it matched. Joined, they're the whole text.
matchedboolean
Whether any piece matched.

AutocompleteItemIcon:

mirrorboolean
Whether it flips in right-to-left text.

Reasons

Why the text changed:

input-changeEvent
Typing, pasting or dropping changed a text field's value; in a combobox it can also open or close it, or Enter keeps the typed text as the value.
item-pressMouseEvent | KeyboardEvent
A member of a collection was chosen: a menu item, a tab, a radio or a checkbox item.
list-navigationKeyboardEvent
Arrow, Home or End keys moved the selection, typing picked an item, or Ctrl or ⌘ with A selected every item of a listbox.
escape-keyKeyboardEvent
Escape, or a submenu's close key (ArrowLeft in left-to-right layouts).
clear-pressMouseEvent | KeyboardEvent
A Clear part was pressed, like on an input, a select or a combobox.
resetnone
A form reset.
imperativenone
A controller or api call, or a property set on a web component.

And why the suggestions opened or closed:

input-changeEvent
Typing, pasting or dropping changed a text field's value; in a combobox it can also open or close it, or Enter keeps the typed text as the value.
item-pressMouseEvent | KeyboardEvent
A member of a collection was chosen: a menu item, a tab, a radio or a checkbox item.
escape-keyKeyboardEvent
Escape, or a submenu's close key (ArrowLeft in left-to-right layouts).
imperativenone
A controller or api call, or a property set on a web component.
trigger-pressMouseEvent | KeyboardEvent | TouchEvent
Click, tap, Enter or Space on the part that opens, closes or toggles. Arrow keys that open a menu or submenu count too. A tap on a combobox's input that opens a sheet reports its touchend.
trigger-focusFocusEvent
Keyboard focus reached a trigger that opens on focus, like a tooltip's.
input-commitKeyboardEvent | FocusEvent
Enter, or leaving a number input, committed what was typed: a number input parses, clamps and snaps it to the step, and an autocomplete closes its suggestions on it.
outside-pressMouseEvent
A press outside the layer.
close-pressMouseEvent | KeyboardEvent | SubmitEvent
A Close part was pressed, or a form with method="dialog" was submitted.
focus-outKeyboardEvent | FocusEvent
Focus left the layer, or Tab moved it out.
window-blurFocusEvent
The window lost focus.
backEvent
Going back: the Android back button or gesture, or Backspace in an empty command input, which returns to the previous page.
swipeTouchEvent | PointerEvent
A swipe gesture: a finger, mouse or pen dragged it.

With dismissible false, the refused dismissals dismissattempt reports:

escape-keyKeyboardEvent
Escape, or a submenu's close key (ArrowLeft in left-to-right layouts).
outside-pressMouseEvent
A press outside the layer.
backEvent
Going back: the Android back button or gesture, or Backspace in an empty command input, which returns to the previous page.
swipeTouchEvent | PointerEvent
A swipe gesture: a finger, mouse or pen dragged it.

Controller

The element's api property has the same methods.

isOpen()() => boolean
Whether the suggestions are open.
setOpen(open, options?)(open: boolean, options?: AutocompleteChangeOptions<AutocompleteOpenChangeReason> | undefined) => boolean
Opens or closes the suggestions. Returns false when the change was canceled or it was already open or closed.
open(options?)(options?: (AutocompleteChangeOptions<AutocompleteOpenChangeReason> & { signal?: AbortSignal | undefined; }) | undefined) => Promise<...>
Opens the suggestions, and resolves once they close, with why and how. Resolves exactly once and never rejects: on the next close, when signal aborts, or with reason "unmount".
close(options?)(options?: AutocompleteChangeOptions<AutocompleteOpenChangeReason> | undefined) => boolean
Closes the suggestions. Returns false when the close was canceled or it was already closed.
toggle(options?)(options?: AutocompleteChangeOptions<AutocompleteOpenChangeReason> | undefined) => boolean
Opens the suggestions when they're closed, and closes them when they're open. Returns false when the change was canceled.
getValue()() => string
The text.
setValue(value, options?)(value: string, options?: AutocompleteChangeOptions<AutocompleteValueChangeReason> | undefined) => boolean
Changes the text, which filters the suggestions. Returns false when the change was canceled or nothing changed.
clear(options?)(options?: AutocompleteChangeOptions<AutocompleteValueChangeReason> | undefined) => boolean
Empties the field. Returns false when the change was canceled or nothing changed.
focus()() => void
Moves focus to the field.

Events

Events fire on <ui-autocomplete> and don't bubble, with the new state in event.detail.value and the reason and event beside it. Calling preventDefault() on valuechange or openchange cancels the change.

MemberOnDescription
value propertyui-autocompleteThe text. Setting it changes the text, as a controller would
open property, attributeui-autocompleteWhether the suggestions are open
api propertyui-autocompleteThe controller
valuechange eventui-autocompletedetail: { value, reason, event, source }
openchange eventui-autocompletedetail: { value: open, reason, event, source }
openchangecomplete eventui-autocompletedetail: { value: open }, after the animation
highlight eventui-autocompletedetail: { value, index, event }
loadmore eventui-autocompleteWhen the last suggestion is reached
submit eventui-autocompletedetail: { value }. Cancel it to keep the form from submitting
dismissattempt eventui-autocompletedetail: { reason, event }, when a dismissal was refused

Accessibility

The autocomplete follows the WAI-ARIA combobox pattern with list autocomplete, and list and inline with inline-complete.

Typing filters the suggestions. Arrow keys move the highlight; Enter fills in the highlighted text and Escape closes the list. Focus usually stays in the input while aria-activedescendant identifies the highlighted suggestion. A touch screen-reader trigger can move focus into the list, and a sheet has its own focus behavior.

Every line below is an automated test.

Field
  • Is a combobox named by its label, with list autocomplete.
  • Typing opens the suggestions that match, and the text stays what was typed.
  • Text that matches nothing stays, with the empty message.
  • Typing in the middle of the text keeps the caret where it was.
Choosing
  • Arrow keys move the highlight while focus stays in the field.
  • Enter fills in the highlighted suggestion and closes, without submitting.
  • Clicking a suggestion fills it in and keeps focus in the field.
  • A disabled suggestion can't be chosen.
  • Escape takes an inline completion back out.
  • Escape closes the suggestions and keeps the text.
Forms
  • Enter with nothing highlighted submits the text as typed.
  • The field submits a chosen suggestion's text under its name.
  • Required blocks submitting an empty field.
  • A disabled field can't be focused or changed.
Clear
  • The clear button empties the field and keeps focus in it.

Runs in React, Vue and web components.

Also tested:

Enhancements
  • Inline completion fills in the first match with the rest selected after the caret.
  • Backspace takes an inline completion out and doesn't complete again.
  • ArrowRight accepts an inline completion.
  • With inline completion, arrow keys fill in the suggestion they highlight.
  • The suggestions open when the field gets focus.
  • Enter with nothing highlighted runs onSubmit with the text.
  • Filtering matches a suggestion's keywords.
  • A form reset puts the default text back.
  • The list is named by the field's label.
  • An immediate search runs once when the autocomplete mounts.
  • A newer search aborts the older one, and only its results land.
  • Arrow keys keep the highlighted item in view when the … scrolls.

Runs in React, Vue and web components.

Screen readers hear the same thing in each tested framework, recorded by a virtual screen reader:

  • Announcements while typing and choosing with a keyboard.

Runs in React, Vue and web components.