Autocomplete
@cloudflare/kumo

Autocomplete

A free-form text input with an optional filtered suggestion list. Unlike Combobox, the value is not constrained to the items list. 

<Autocomplete items={fruits}>
  <Autocomplete.InputGroup placeholder="Search fruits…" />
  <Autocomplete.Content>
    <Autocomplete.List>
      {(item: string) => (
        <Autocomplete.Item key={item} value={item}>
          {item}
        </Autocomplete.Item>
      )}
    </Autocomplete.List>
  </Autocomplete.Content>
</Autocomplete>

const fruits = [
  "Apple", "Banana", "Cherry", "Grape",
  "Lemon", "Mango", "Orange", "Peach",
];

Installation

Barrel 

import { Autocomplete } from "@cloudflare/kumo";

Granular

import { Autocomplete } from "@cloudflare/kumo/components/autocomplete";

When to use

Use Autocomplete when the input value can be free-form text and suggestions are optional hints. Use Combobox instead when the selected value must come from the predefined list.

Controlled

Pass value and onValueChange for controlled usage. 

function App() {
  const [value, setValue] = useState("");

  return (
    <Autocomplete
      items={fruits}
      value={value}
      onValueChange={(v) => setValue(v)}
    >
      <Autocomplete.InputGroup placeholder="Type a fruit…" />
      <Autocomplete.Content>
        <Autocomplete.List>
          {(item: string) => (
            <Autocomplete.Item key={item} value={item}>
              {item}
            </Autocomplete.Item>
          )}
        </Autocomplete.List>
        <Autocomplete.Empty />
      </Autocomplete.Content>
    </Autocomplete>
  );
}

With Field

Add label, description, and required to enable the built-in Field wrapper.

Start typing to filter countries

 
<Autocomplete
  items={countries}
  label="Country"
  description="Start typing to filter countries"
  filter={(item, query) =>
    item.label.toLowerCase().includes(query.toLowerCase())
  }
>
  <Autocomplete.InputGroup placeholder="Search countries…" />
  <Autocomplete.Content>
    <Autocomplete.List>
      {(item: Country) => (
        <Autocomplete.Item key={item.code} value={item}>
          {item.label}
        </Autocomplete.Item>
      )}
    </Autocomplete.List>
  </Autocomplete.Content>
</Autocomplete>

Error State

Display validation errors with the error prop.

Please enter a valid country
 
<Autocomplete
  items={countries}
  label="Country"
  error={{ message: "Please enter a valid country", match: true }}
  filter={(item, query) =>
    item.label.toLowerCase().includes(query.toLowerCase())
  }
>
  <Autocomplete.InputGroup placeholder="Search countries…" />
  <Autocomplete.Content>
    <Autocomplete.List>
      {(item: Country) => (
        <Autocomplete.Item key={item.code} value={item}>
          {item.label}
        </Autocomplete.Item>
      )}
    </Autocomplete.List>
  </Autocomplete.Content>
</Autocomplete>

Grouped

Group items into categories using Autocomplete.Group and Autocomplete.GroupLabel. 

<Autocomplete items={servers}>
  <Autocomplete.InputGroup placeholder="Select region…" />
  <Autocomplete.Content>
    <Autocomplete.List>
      {(group: ServerGroup) => (
        <Autocomplete.Group key={group.value} items={group.items}>
          <Autocomplete.GroupLabel>{group.value}</Autocomplete.GroupLabel>
          <Autocomplete.Collection>
            {(item: ServerLocation) => (
              <Autocomplete.Item key={item.value} value={item}>
                {item.label}
              </Autocomplete.Item>
            )}
          </Autocomplete.Collection>
        </Autocomplete.Group>
      )}
    </Autocomplete.List>
  </Autocomplete.Content>
</Autocomplete>

Sizes

The size prop on Autocomplete.InputGroup supports four variants matching the Input component: xs, sm, base (default), and lg. 

<Autocomplete items={fruits}>
  <Autocomplete.InputGroup size="sm" placeholder="sm" />
  <Autocomplete.Content>
    <Autocomplete.List>
      {(item: string) => (
        <Autocomplete.Item key={item} value={item}>{item}</Autocomplete.Item>
      )}
    </Autocomplete.List>
  </Autocomplete.Content>
</Autocomplete>

Custom Filtering

By default, Base UI filters items using a built-in string match. Pass a custom filter function for advanced logic such as fuzzy matching or object properties. 

// Filter on a property of object items
<Autocomplete
  items={countries}
  filter={(item, query) =>
    item.label.toLowerCase().includes(query.toLowerCase())
  }
>
  ...
</Autocomplete>

// Disable filtering entirely (e.g. async search)
<Autocomplete items={results} filter={null}>
  ...
</Autocomplete>

API Reference

Autocomplete

Root component. Wraps all sub-components and manages state.

PropTypeDefaultDescription
size"xs" | "sm" | "base" | "lg""base"Size of the autocomplete input. Matches Input component sizes. - `"xs"` — Extra small for compact UIs (h-5 / 20px) - `"sm"` — Small for secondary fields (h-6.5 / 26px) - `"base"` — Default size (h-9 / 36px) - `"lg"` — Large for prominent fields (h-10 / 40px)
items*unknown[]-Array of items to display in the dropdown
valuestring | number | string[]-The controlled input value
openboolean-Whether the popup is open (controlled)
childrenReactNode-Autocomplete content (input group, popup content)
classNamestring-Additional CSS classes
labelReactNode-Label content (enables Field wrapper)
requiredboolean-Whether the field is required
labelTooltipReactNode-Tooltip content to display next to the label
descriptionReactNode-Helper text displayed below the field
errorstring | object-Error message or validation error object

Autocomplete.InputGroup

Self-contained input wrapper that renders the text input, clear button, and dropdown trigger together.

PropTypeDefault
classNamestring-
sizeKumoAutocompleteSize-
placeholderstring-

Autocomplete.Content

Dropdown popup container. Wraps Portal, Positioner, and Popup.

PropTypeDefault
childrenReactNode-
classNamestring-
alignAutocompleteBase.Positioner.Props["align"]-
alignOffsetAutocompleteBase.Positioner.Props["alignOffset"]-
sideAutocompleteBase.Positioner.Props["side"]-
sideOffsetAutocompleteBase.Positioner.Props["sideOffset"]-

Autocomplete.Item

Individual suggestion item in the list.

PropTypeDefault

No component-specific props. Accepts standard HTML attributes.

Additional Sub-components

  • Autocomplete.List — scrollable list container with render prop
  • Autocomplete.Group — groups items under a heading
  • Autocomplete.GroupLabel — heading label for a group
  • Autocomplete.Collection — item container within a group
  • Autocomplete.Separator — horizontal divider between items