Read page as text

NIB / DOCUMENTATION

Combobox — NibComponents

Search a local list, allow free text, or exercise a bounded async fixture.

Open interactive view

Own selection separately from the query

NibComboboxController exposes selectedValue, selectedValues, query, and isOpen. selectOnly, toggle, and clear change selection; open and close change the panel state. query is a readout of the field. setQuery is a low-level mirror and does not itself replace the visible editing value. The example keeps one controller through theme or animation changes and disposes it on removal.

Choose chips or submit free text

multiSelect keeps several selected values and displays chips. onSelectionChanged supplies the complete selection. allowFreeText enables onFreeTextSubmitted for text that is not a chosen option; it does not fabricate a typed option value. The demo records that submission as an event without pretending it came from the list.

Use the async loader contract

NibComboboxOptionsLoader<T> maps the current query to a Future<List<NibComboboxOption<T>>>. debounceDuration defaults to 300 ms. The widget ignores stale results when a newer request wins; your service still owns cancellation, authorization, failures, and resource limits. The Async fixture waits 220 ms and filters an in-memory list. It sends no network traffic.

NibCombobox<String>(
  asyncOptionsLoader: (query) async => repository.search(query),
  debounceDuration: const Duration(milliseconds: 300),
  onChanged: (value) => setState(() => selected = value),
)

Keep the field and dropdown consistent

clearable defaults to true, disabled to false, and maxDropdownHeight to 280. loading presents pending work; it does not invoke the loader. backgroundColor, borderColor, borderWidth, borderRadius, padding, and hintStyle override theme defaults. animated opts into a short dropdown entrance.

Use the editable field as the focus entry point

Typing filters results, arrows move the highlighted option, Enter activates it or submits permitted free text, and Escape closes and restores the selected label when free text is off. Multi-select Backspace can remove the last chip when the query is empty. Verify your host’s text editing and focus behavior as well as pointer selection.

The list is empty or a query is not visible

Inspect loading, filtering, disabled options, and whether the async fixture has completed. Controller.open() in this candidate does not initialize the visible option list until the field interaction populates it; use the field to open this demo. Do not claim that setQuery is a full text-controller API. A fresh controller on every rebuild loses selection and query state.

Limits and platform evidence

Controller.open() alone does not populate options before the first field interaction in this candidate.