React Combobox: Async-Suche ohne Race Conditions

Eine React Combobox ist das Feld, in das man „san“ tippt und darunter San Diego aus einer Liste wählt. Die erste Version steht nach einem Nachmittag: ein Input, ein gefiltertes Array, ein Popup. Dann kommt die Liste vom Server, und eine alte Antwort überschreibt eine neuere. „jose“ findet „José“ nicht, die Pfeiltasten scrollen die Seite statt der Liste, und auf dem Handy liegt das Popup unter der Tastatur. Dieser Guide zeigt, wann eine Combobox das richtige Element ist und wann ein Select oder eine Listbox besser passt. Außerdem baust du ein Autocomplete mit Serversuche, und zwar mit der Combobox von Wingo UI, unserer eigenen Bibliothek.

Was ist eine Combobox, und was unterscheidet sie von Select und Listbox?

Eine Combobox ist ein Textfeld mit einem Popup voller Vorschläge, ein Select ist ein Button, der eine Liste öffnet, und eine Listbox ist die Liste selbst, immer sichtbar auf der Seite. Alle drei nutzen dieselben ARIA-Bausteine. Der Unterschied liegt darin, wo die Auswahl stattfindet und ob man tippt.

Das WAI-ARIA Combobox Pattern (opens in a new tab) beschreibt eine Combobox als Eingabefeld mit einem Popup, meist einer Listbox, das beim Setzen des Werts hilft. Eine editierbare Combobox hat ein Textfeld. Eine Select-only-Combobox hat keins und verhält sich wie ein natives <select>. Eine einfache Listbox ist die Liste selbst, immer auf der Seite, ohne Popup.

Unsere Faustregel: Wenn Nutzer wissen, was sie suchen, und Tippen schneller geht als Scrollen, nimm eine Combobox. Wenn sie die Optionen sehen müssen, um sich zu entscheiden, nimm ein Select. Wenn die Optionen der Hauptinhalt dieses Bildschirmbereichs sind, nimm eine Listbox. Zwei bis fünf Optionen, die man vergleichen soll, gehören in eine Radio Group oder ein Segmented Control, wie der Guide zu React-Formularkomponenten erklärt.

Was muss eine React Combobox mit Suche können?

Eine React Combobox mit Suche muss sieben Dinge können, die über das Filtern eines Arrays hinausgehen: Schreibweisen, Aliasse, asynchrone Ergebnisse, Tastatur, das Übernehmen des Texts, Handys und Formulare. Unsere Checkliste:

• Schreibweisen erkennen. Groß- und Kleinschreibung und diakritische Zeichen spielen nie eine Rolle, jedes Wort muss passen, die besten Treffer stehen oben, passende Buchstaben sind fett.
• Aliasse. „St. Louis“ soll Saint Louis finden und „NY“ New York. Suchbegriffe, die nicht im Label stehen, gehören in die keywords der Option. Sie zählen etwas weniger als ein Treffer im Label.
• Asynchrone Ergebnisse. Entprellen, die ältere Anfrage abbrechen, die alten Zeilen stehen lassen, bis die neuen da sind, einen Fehler mit Wiederholen-Button zeigen.
• Tastatur. Die ARIA-Tasten, wobei der Fokus im Eingabefeld bleibt.
• Text übernehmen. Verliert das Feld den Fokus, springt der Text auf die gewählte Option zurück oder wird zum Wert, nie etwas dazwischen.
• Handys. Ein Popup unter einem Textfeld landet unter der Tastatur.
• Formulare. Der Wert der Option, nicht das Label, das man liest, kommt in FormData und in deiner Formularbibliothek an.

Wie baue ich eine async React Combobox mit Serversuche?

Übergib eine loadOptions-Funktion und überlass das Timing der Komponente. Installier zuerst die Combobox. Die CLI kopiert den Quellcode in dein Projekt und ergänzt, was er importiert (die Listbox, die Feld-Anatomie, den Text-Matcher):

npx wingo-ui@latest add combobox

Die Prop loadOptions bekommt den Suchbegriff und ein AbortSignal und gibt die Optionen zurück. Das ist das komplette Feld:

"use client"

import { useState } from "react"
import { MapPin } from "lucide-react"
import { Combobox, type ComboboxItems } from "@/components/ui/combobox"

async function searchCities(query: string, { signal }: { signal: AbortSignal }): Promise<ComboboxItems> {
  const response = await fetch(`/api/cities?q=${encodeURIComponent(query)}`, { signal })
  if (!response.ok) throw new Error(`Stadtsuche fehlgeschlagen: ${response.status}`)
  const cities: { id: string; name: string; state: string }[] = await response.json()
  return cities.map((city) => ({ value: city.id, label: city.name, description: city.state }))
}

export function CityField() {
  const [city, setCity] = useState("")
  return (
    <Combobox
      label="Stadt"
      placeholder="Nach einer Stadt suchen"
      leftIcon={<MapPin />}
      loadOptions={searchCities}
      minQueryLength={1}
      value={city}
      onValueChange={setCity}
      emptyText="Keine Städte gefunden"
      errorText="Städte konnten nicht geladen werden"
      sheetTitle="Städte suchen"
      name="city"
    />
  )
}

Wer in einer React Combobox async sucht, kämpft vor allem mit dem Timing, und das übernimmt die Komponente:

• Sie wartet debounce Millisekunden Ruhe ab (standardmäßig 250), bevor sie loadOptions aufruft, und erst ab minQueryLength Zeichen. Der allererste Ladevorgang läuft sofort, damit die ersten Ergebnisse nicht hinterherhinken.
• Eine neuere Suche bricht die ältere Anfrage über das Signal ab, das du an fetch weitergibst, und eine verspätete Antwort überschreibt nie eine neuere.
• Die vorigen Ergebnisse bleiben sichtbar, während die nächsten laden, mit einem Spinner im Feld. So blinkt die Liste nicht bei jedem Tastendruck leer.
• Die letzten 20 Antworten landen im Cache, mit dem getrimmten Suchbegriff als Schlüssel. Gehst du per Backspace zu einer früheren Suche zurück, sind die Ergebnisse sofort da. Fehlgeschlagene Anfragen landen nicht im Cache.
• Ein abgelehntes Promise zeigt errorText mit einem Wiederholen-Button (retryLabel), und die letzten Ergebnisse bleiben stehen.

Wirf bei einer Antwort ohne OK-Status unbedingt einen Fehler. Ein 500er, der mit einem Fehler-Body auflöst, erscheint sonst als „Keine Städte gefunden“, und deine Nutzer glauben, die Stadt gebe es nicht.

Die Fake-API der Demo antwortet nach 400ms. So siehst du, wie die alten Ergebnisse stehen bleiben, während die neuen laden.

Wie ignoriert die Suche Akzente und Groß- und Kleinschreibung?

Normalisiere beide Seiten auf dieselbe Weise. Kleinschreiben, mit Unicode NFD zerlegen, die kombinierenden Zeichen entfernen: Aus „José“ wird „jose“, aus „Zürich“ wird „zurich“. Buchstaben, die nicht zerfallen, wie „ß“ oder „ø“, brauchen eine kleine Tabelle.

Für lokale Optionen erledigt das die Combobox über den Helper text-match, der mitgeliefert wird und nicht von React abhängt. Der Helper ist auch einzeln kostenlos (npx wingo-ui@latest add text-match), und du kannst dieselbe Funktion in einem Next.js Route Handler importieren, damit der Server exakt gleich sucht:

// app/api/cities/route.ts
import { filterByText } from "@/lib/text-match"
import { CITIES } from "@/data/cities"

export async function GET(request: Request) {
  const query = new URL(request.url).searchParams.get("q") ?? ""
  const results = filterByText(CITIES, query, (city) => [city.name, city.state], { limit: 20 })
  return Response.json(results.map((result) => result.item))
}

filterByText gibt die Einträge sortiert zurück, die besten zuerst: ein exakter Treffer, dann ein Präfix des ganzen Texts, dann ein Wortpräfix, dann ein Treffer mitten im Wort. Keywords nach dem Label zählen etwas weniger. CITIES ist dein eigenes Array aus { id, name, state }.

Bei einer Datenbank normalisierst du stattdessen in der Abfrage. PostgreSQL liefert die Erweiterung unaccent (opens in a new tab) mit, deren Funktion unaccent() die Akzente entfernt (unaccent('Hôtel') gibt Hotel zurück). Speicher den normalisierten, kleingeschriebenen Namen in einer eigenen Spalte und indexier sie. Dann muss die Datenbank nicht bei jedem Tastendruck jede Zeile neu normalisieren.

Zwei weitere Props ändern das Matching im Client. Mit fuzzy dürfen zwischen den Buchstaben Lücken sein, also findet „sfco“ San Francisco. filter={false} sagt der Komponente, dass deine Optionen schon gefiltert sind.

Welche Tasten sollte eine Combobox unterstützen?

Eine Combobox sollte die Pfeiltasten, Enter, Escape und Tab unterstützen, während der Fokus im Textfeld bleibt, so wie es das WAI-ARIA Pattern beschreibt. Die Combobox belegt sie so:

Der Fokus bleibt die ganze Zeit im Input. Der Input hat role="combobox", aria-autocomplete="list", aria-expanded, aria-controls, das auf die offene Liste zeigt, und aria-activedescendant, das auf die markierte Zeile zeigt. So lesen Screenreader die Zeile vor, während der Cursor dort bleibt, wo du getippt hast.

autoHighlight (standardmäßig an) markiert den ersten Treffer, damit Enter ihn wählt. Schalte es aus, wenn das Feld freien Text annimmt, denn dann soll Enter das Getippte behalten.

Wann sollte die Combobox freien Text annehmen?

Nimm freien Text an, wenn jede Antwort gültig ist und die Vorschläge nur Tipparbeit sparen. Verlang eine Option, wenn der Wert in deinen Daten existieren muss. Standardmäßig springt der Text beim Verlassen des Felds auf die gewählte Option zurück oder leert sich, wenn nichts gewählt wurde. Das passt für eine Stadt, die in deiner Datenbank existieren muss.

Bei einer Straßenadresse ist das anders: Vorschläge helfen, aber jede Straße ist gültig. Übergib allowCustomValue, und der getippte Text wird beim Verlassen oder bei Enter zum Wert. Das ist das React Autocomplete, das die meisten Adressformulare brauchen. Base UI löst denselben Fall mit einer eigenen Autocomplete-Komponente, weil dessen Combobox keinen freien Text erlaubt.

Sollen Nutzer eine fehlende Option selbst in die Liste aufnehmen, nimm creatable. Eine „Create“-Zeile erscheint, wenn nichts exakt passt, und onCreate darf ein Promise zurückgeben. Die Zeile zeigt einen Spinner, bis es auflöst, dann wird der zurückgegebene Wert gewählt:

"use client"

import { useState } from "react"
import { Combobox, type ComboboxOption } from "@/components/ui/combobox"

async function createMake(name: string): Promise<{ id: string }> {
  const response = await fetch("/api/makes", { method: "POST", body: JSON.stringify({ name }) })
  if (!response.ok) throw new Error(`${name} konnte nicht angelegt werden`)
  return response.json()
}

export function MakeField({ initialMakes }: { initialMakes: ComboboxOption[] }) {
  const [makes, setMakes] = useState(initialMakes)
  const [make, setMake] = useState("")
  return (
    <Combobox
      label="Automarke"
      options={makes}
      value={make}
      onValueChange={setMake}
      creatable
      onCreate={async (name) => {
        const created = await createMake(name)
        setMakes((current) => [...current, { value: created.id, label: name }])
        return created.id
      }}
    />
  )
}

Die neue Option fügst du selbst zu options hinzu, wie oben. Die Combobox wählt den zurückgegebenen Wert, aber die Liste gehört dir.

Wie funktioniert eine Combobox auf dem Handy?

Auf dem Handy öffnet die Combobox statt eines Popups ein Such-Sheet in voller Höhe. Die Tastatur belegt die untere Hälfte des Bildschirms, ein Popup unter dem Feld würde also von ihr verdeckt. Unter 768px holt das Feld auf der Seite selbst nie die Tastatur hoch. Ein Tipp öffnet das Sheet mit einem Suchfeld oben, das den Fokus bekommt, damit die Tastatur dort erscheint, dazu einen „Cancel“-Button (cancelLabel) und 48px hohe Zeilen. Ein Tipp auf ein Ergebnis füllt das Feld und schließt das Sheet, und die Suchtaste der Tastatur wählt das erste Ergebnis. Mit responsive={false} behältst du das Popup.

Das Select geht den umgekehrten Weg: ein Bottom Sheet mit dem Label als Titel, und seine Suchzeile wartet auf einen Tipp, weil man eine kurze Liste meist scrollt, statt zu tippen.

Hat shadcn/ui eine Combobox mit async Suche?

Ja, shadcn/ui hat eine Combobox, aber die Doku zur shadcn Combobox enthält kein Beispiel für Serversuche. Den asynchronen Teil schreibst du also selbst. Stand Oktober 2026 bietet die Seite zur shadcn/ui Combobox (opens in a new tab) Versionen für Base UI, Radix UI und React Aria. Die Standardversion mit Base UI verlinkt für ihre API auf die Base UI Combobox (opens in a new tab) und zeigt Gruppen, einen Löschen-Button, ein Input-Group-Addon und Mehrfachauswahl mit Chips. Ein Beispiel für Serversuche oder das Anlegen einer fehlenden Option gibt es nicht.

Das ältere Rezept, das viele Tutorials noch kopieren und das im shadcn-Repo weiterhin als combobox-demo.tsx (opens in a new tab) liegt, setzt ein Popover mit der Command-Komponente (cmdk) zusammen. Serversuche heißt dort: den eingebauten Filter von cmdk mit shouldFilter={false} abschalten, wie es das README von cmdk (opens in a new tab) dokumentiert, und dann die Ergebnisse rendern, die du selbst geholt hast.

Für die async Suche übergeben die Beispiele von Base UI filter={null}, starten eine Suche in onInputValueChange, brechen die vorige Suche über deren AbortController ab, damit eine veraltete Antwort verworfen wird, und rendern Lade- und Fehlertext aus ihrem eigenen State. Das ist Beispielcode, den du kopierst und pflegst. Er entprellt nicht, und das Signal wird nicht an den Fake-Fetch weitergegeben, also läuft eine ältere Anfrage trotzdem bis zum Ende. Wenn du diesen Weg gehst, ergänze das Entprellen, gib das Signal an fetch weiter und entscheide, was das Feld auf dem Handy tut. Unser Guide zur Command Palette behandelt den verwandten Fall, in dem man Aktionen statt Werte sucht.

Wann ist eine Listbox die bessere Wahl?

Eine Listbox ist die bessere Wahl, wenn die Optionen der Hauptinhalt dieses Bereichs sind: Filter in einer Sidebar, ein Schritt in einem Onboarding-Flow, eine Auswahl in einem offenen Sheet. Ein Popup kostet dort einen zusätzlichen Tipp und versteckt die Auswahl. Die Listbox rendert dieselben Zeilen direkt auf der Seite, mit optionaler Suchzeile (search), multiple mit Checkboxen, loadOptions für Serversuche mit derselben Entprellung und demselben Cache, und creatable.

Select und Listbox sind kostenlos. Für mehrere Werte in einem Popup behandelt der Guide zum React Multi Select das Multi Select, und der Guide zum Tag Input den Fall, in dem Nutzer eigene Werte eintippen.

Welche Fehler passieren bei einer Combobox am häufigsten?

• Den ersten Treffer in einem Freitextfeld markieren. Schalte mit allowCustomValue auch autoHighlight aus, sonst ersetzt Enter, was getippt wurde.
• Ein Wert ohne Label. Wenn der kontrollierte value nicht in den aktuellen Ergebnissen steht, braucht das Feld den Text der Option. Die Combobox merkt sich den Text der Optionen, die sie gesehen hat, und zeigt sonst den rohen Wert.
• Das Label statt des Werts absenden. Übergib name, dann geht der Wert der Option (san-diego, nicht „San Diego“) über ein verstecktes Input mit, und FormData und Server Actions bekommen die ID. Bei register aus react-hook-form ist das anders: Es liest das Textfeld und dessen natives onChange, speichert also, was getippt wird. Mit allowCustomValue ist das richtig. Für Optionswerte nimm Controller und verbinde value und onValueChange.
• Veraltete Antworten im Cache. Mit loadOptions lebt der Cache für 20 Suchen so lange, wie das Feld gemountet ist, und hat kein Ablaufdatum. Nach einem Schreibvorgang, der ändert, was der Server zurückgibt, zeigt eine schon getippte Suche die alte Antwort. Gib der Combobox deshalb einen neuen key, wenn sich deine Daten ändern.

Wie geht es weiter?

Installier die Combobox mit npx wingo-ui@latest add combobox und richte loadOptions auf deinen Such-Endpunkt. Sie ist eine Pro-Komponente (zu den Preisen); Select und Listbox sind kostenlos. Weitere Guides wie diesen findest du in der Kategorie Komponenten-Guides.

Häufige Fragen

Was ist der Unterschied zwischen einer Combobox und einem Select?

Eine Combobox hat ein editierbares Textfeld: Du tippst, um die Optionen zu filtern, und manche Comboboxen nehmen auch Text an, der nicht in der Liste steht. Ein Select ist ein Button, der eine Liste öffnet, die du scrollst oder durchsuchst, und sein Wert ist immer eine der Optionen. Die WAI-ARIA Authoring Practices nennen eine Combobox ohne Textfeld eine Select-only-Combobox und vergleichen sie mit einem HTML-Select.

Ist eine Combobox dasselbe wie ein Autocomplete?

Weitgehend. Autocomplete beschreibt das Verhalten (Vorschläge beim Tippen), Combobox ist die ARIA-Rolle des Eingabefelds, das sie zeigt. Manche Bibliotheken trennen beides: Stand Oktober 2026 schreibt die Doku von Base UI, dass ihre Combobox keinen freien Text erlaubt, und verweist für Such-Widgets auf die eigene Autocomplete-Komponente.

Wie mache ich eine React Combobox async?

Warte auf eine kurze Tipppause (250ms sind ein guter Standard), schick die Suche mit einem AbortSignal, brich die vorige Anfrage ab, sobald eine neue startet, und ignorier jede Antwort, die nach einer neueren Suche eintrifft. Lass die vorigen Ergebnisse mit einem Spinner stehen, statt die Liste bei jedem Tastendruck zu leeren.

Wie bringe ich eine Combobox dazu, Akzente zu ignorieren?

Normalisiere Suchbegriff und Optionstext vor dem Vergleich: kleinschreiben, Unicode NFD, dann die kombinierenden Zeichen entfernen, damit „jose“ auch „José“ findet. Buchstaben wie ß und ø lassen sich nicht zerlegen und brauchen eine kleine Tabelle. Auf dem Server nutzt du dieselbe Funktion oder das Werkzeug der Datenbank, etwa die PostgreSQL-Erweiterung unaccent.

Hat shadcn/ui eine Combobox?

Ja. Stand Oktober 2026 bietet die Combobox-Doku von shadcn/ui Versionen für Base UI, Radix UI und React Aria, und die Standardseite für Base UI zeigt Gruppen, einen Löschen-Button und Mehrfachauswahl mit Chips. Ein Beispiel für Serversuche oder das Anlegen neuer Optionen gibt es dort nicht, diesen Teil schreibst du selbst.