Autocomplete

Preview

Local preview. It doesn't affect real accounts, environments, or run data.

Usage

Suggest values for search and tag inputs that don't require a selection. Typed text is valid even without a matching suggestion. Root.value is the input string, not a selected ID.

Use Combobox when users must pick a registered resource. Don't treat text outside the suggestions as an error. Accept it as typed. Don't submit the form unannounced right after a selection. Announce it, or keep submitOnItemClick off.

Size: SizeProvider size="small" resizes the whole composition, including portals. The default size is Default. Size guidance and comparisons

Anatomy

Root → Field(label/description/error) + InputGroup(Input/Clear/Trigger) + Content(Empty/Status + List/Item)

Keyboard and accessibility

Typing narrows the suggestions. Arrow keys and Enter complete the text. Escape or Tab closes the popup. By default, selecting an item doesn't submit the form. Base UI types for non-string object suggestions and grouped items are preserved.

Give each control a name that describes its purpose. Connect error messages to their controls, and signal state with more than color. Automated checks don't replace manual keyboard and assistive technology testing.

Example code

Shared components take their styles from design tokens. Each example sets its own composition and accessibility attributes. The calling screen defines callbacks, refs, and product data.

import { Autocomplete, Field } from '@surflane/ui'

<Field.Root name='query'>
  <Field.Label>Pipeline search</Field.Label>
  <Autocomplete.Root name='query' items={suggestions}>
    <Autocomplete.InputGroup>
      <Autocomplete.Input placeholder='Search scenarios…' />
      <Autocomplete.Clear />
      <Autocomplete.Trigger />
    </Autocomplete.InputGroup>
    <Autocomplete.Content>
      <Autocomplete.Empty>
        No suggestions. Free text is accepted.
      </Autocomplete.Empty>
      <Autocomplete.List>
        {(item: string) => (
          <Autocomplete.Item key={item} value={item}>
            {item}
          </Autocomplete.Item>
        )}
      </Autocomplete.List>
    </Autocomplete.Content>
  </Autocomplete.Root>
  <Field.Error />
</Field.Root>

Key API

The table lists the common wrapper's main props. See the package type declarations for the full types.

Related tokens