Autocomplete: Select or combobox

The Autocomplete is a combobox by default: its popup holds a search box that filters the options as you type. Set searchable to false and the same component is a select: no search box, and typing jumps to a matching option.

searchable autoHighlight

Nothing selected.

import { useState } from "react";
import { Autocomplete, type OptionValue } from "slotsmith/autocomplete";
import { countries, type Country } from "../shared/options";

export default function SelectOrCombobox() {
  const [searchable, setSearchable] = useState(true);
  const [autoHighlight, setAutoHighlight] = useState(false);
  const [country, setCountry] = useState<OptionValue | null>(null);

  return (
    <div style={{ display: "grid", gap: "1rem", maxWidth: 360 }}>
      <div style={{ display: "flex", flexWrap: "wrap", gap: "0.5rem 1.5rem" }}>
        <label>
          <input type="checkbox" checked={searchable} onChange={(event) => setSearchable(event.target.checked)} /> <code>searchable</code>
        </label>
        <label>
          <input type="checkbox" checked={autoHighlight} onChange={(event) => setAutoHighlight(event.target.checked)} /> <code>autoHighlight</code>
        </label>
      </div>
      <Autocomplete<Country>
        options={countries}
        getOptionValue={(entry) => entry.code}
        getOptionLabel={(entry) => entry.name}
        // true: a search box filters the list. false: no search box; typing jumps to the first match.
        searchable={searchable}
        // true: the first match is highlighted as the list opens and narrows, so Enter picks it.
        autoHighlight={autoHighlight}
        value={country}
        onChange={setCountry}
        aria-label="Country"
      />
      <p>{country === null ? "Nothing selected." : `Selected: ${country}`}</p>
    </div>
  );
}

export type Country = { code: string; name: string };

/** Sorted by name, as a picker shows them. */
export const countries: Country[] = [
  { code: "ar", name: "Argentina" },
  { code: "au", name: "Australia" },
  { code: "br", name: "Brazil" },
  { code: "ca", name: "Canada" },
  { code: "eg", name: "Egypt" },
  { code: "fr", name: "France" },
  { code: "de", name: "Germany" },
  { code: "in", name: "India" },
  { code: "jp", name: "Japan" },
  { code: "jo", name: "Jordan" },
  { code: "ke", name: "Kenya" },
  { code: "mx", name: "Mexico" },
  { code: "ma", name: "Morocco" },
  { code: "nl", name: "Netherlands" },
  { code: "no", name: "Norway" },
  { code: "pt", name: "Portugal" },
  { code: "sa", name: "Saudi Arabia" },
  { code: "za", name: "South Africa" },
  { code: "es", name: "Spain" },
  { code: "se", name: "Sweden" },
  { code: "tr", name: "Türkiye" },
  { code: "ae", name: "United Arab Emirates" },
  { code: "gb", name: "United Kingdom" },
  { code: "us", name: "United States" },
];

/** `id` and `label` are the names the autocomplete reads by default, so topics need no getters. */
export type Topic = { id: string; label: string; archived?: boolean };

export const topics: Topic[] = [
  { id: "accessibility", label: "Accessibility" },
  { id: "animation", label: "Animation" },
  { id: "caching", label: "Caching" },
  { id: "design-systems", label: "Design systems" },
  { id: "forms", label: "Forms" },
  { id: "i18n", label: "Internationalisation" },
  { id: "performance", label: "Performance" },
  { id: "rtl", label: "Right-to-left" },
  { id: "server-components", label: "Server components" },
  { id: "state", label: "State" },
  { id: "testing", label: "Testing" },
  { id: "typescript", label: "TypeScript" },
  { id: "legacy", label: "Legacy browsers", archived: true },
];

/** A country with the region it is listed under; a `disabled` one stays in the list but cannot be picked. */
export type RegionCountry = Country & { region: string; disabled?: boolean };

/** A short list grouped by region. Groups show in the order of their first option, so the regions come in this order. */
export const countriesByRegion: RegionCountry[] = [
  { code: "de", name: "Germany", region: "Europe" },
  { code: "fr", name: "France", region: "Europe" },
  { code: "es", name: "Spain", region: "Europe" },
  { code: "ge", name: "Georgia", region: "Europe" },
  { code: "dz", name: "Algeria", region: "Africa" },
  { code: "eg", name: "Egypt", region: "Africa" },
  { code: "ng", name: "Nigeria", region: "Africa" },
  { code: "ne", name: "Niger", region: "Africa", disabled: true },
  { code: "jp", name: "Japan", region: "Asia" },
  { code: "sg", name: "Singapore", region: "Asia" },
  { code: "sa", name: "Saudi Arabia", region: "Asia" },
  { code: "sy", name: "Syria", region: "Asia" },
];

Untick searchable and focus the picker, then type J: the popup opens on Japan. Type J again for Jordan.

Combobox

With searchable on, opening the popup moves focus to its search box, and the list narrows as you type. The default filter matches anywhere in the label and ignores case and accents, so “turk” finds “Türkiye”.

filter takes your own predicate, (option, query) => boolean, or false to show every option whatever the query, as remote options do.
searchQuery with onSearchChange controls the text; minChars holds the search back until enough characters are typed (see the states).
Closing the popup clears the search, so it reopens on the full list.

Select

With searchable={false} there is no search box, and focus stays on the trigger while the popup is open. Typing works like a native <select>:

Letters typed within 0.7 seconds of each other build one search: “ca” lands on the first option starting with “ca”, and only if none does, on one containing it.
The same letter again moves to the next option starting with it, so J, J goes from Japan to Jordan.
Typing on the closed trigger opens the popup on the match.

Highlighting the top match

By default nothing is highlighted until you press an arrow key, so Enter on a fresh search picks nothing. Tick autoHighlight in the demo, open the picker and type “nor”: Norway is highlighted, and Enter picks it.

With autoHighlight, the first option that can be picked is highlighted whenever the list opens and whenever its contents change: as the search narrows it, or as a remote page arrives. Disabled options are skipped. A highlight you move with the arrow keys or the pointer stays put until the search changes. While a first page is still loading nothing is highlighted, so a row from the previous search is never picked.

It suits a picker people drive from the keyboard, where typing a few letters and pressing Enter is the fast path. It works the same with search in the trigger.

Options and values

Options are any objects. By default the autocomplete reads an option’s id from value (or id) and its text from label (or name); getOptionValue and getOptionLabel read other shapes, as the demo does with code and name. Values are strings or numbers.

In single mode, value is the selected id or null, and onChange receives the new id and its option. Leave them out and use defaultValue for a picker that keeps its own value. clearable (on by default) shows a clear button while something is selected, and placeholder sets the text shown while nothing is.

A selected option stays labelled after the search narrows it out of the list. For a value whose option is not in options at all, as when a form loads a saved id before its options, pass the option as selected.