Search

Single choice with a filter line above the options. Typing fuzzy-matches and ranks the labels - exact and prefix matches lead, looser subsequence matches follow - and highlights the matched characters. It collects the selected option value (a string).

$p->search('vegetable', 'Vegetable')
  ->options([
    'carrot' => 'Carrot',
    'potato' => 'Potato',
    'onion' => 'Onion',
    'pepper' => 'Pepper',
  ])
  ->default('carrot') // Which option starts highlighted.
  ->pageSize(8);      // Matches visible before the list pages around the cursor.

Runnable scripts: playground/02-widgets-search.php and search-multiple.php.

Options

Name	Description	Required	Default
options()	The choices, as a value => label map (or added one at a time with option()).	Yes	-
default()	Which option starts highlighted, by value.	No	First option
pageSize()	Matches shown before the list pages around the cursor.	No	10

For headings, separators and disabled options, see Option groups. For a per-option description line shown beneath the highlighted match, declare it with ->option(..., description: ...).

Keyboard

Key	Action
printable keys	Type to fuzzy-filter and rank the options
↑ / ↓	Move over the matches
Backspace	Delete a filter character
Enter	Accept the highlighted option
Esc	Cancel

Display modes

In all four display modes - Unicode or ASCII, color on or off:

	ANSI	No ANSI
Unicode
ASCII

Multiple selection

Add ->multiple() to collect a list<string> of checked values under the filter line. Typing fuzzy-matches and ranks with the matched characters highlighted, Space toggles, → / ← select or deselect all visible, and Enter accepts the checked set.

$p->search('basket', 'Basket')
  ->multiple()
  ->options([
    'apple' => 'Apple',
    'banana' => 'Banana',
    'carrot' => 'Carrot',
    'tomato' => 'Tomato',
  ])
  ->default(['apple']);

	ANSI	No ANSI
Unicode
ASCII

Selection limits

Bound how many values a multiple field collects with ->minSelections() and ->maxSelections(). The active limit shows as a hint below the list, an out-of-range selection is rejected inline when you accept, and the same bounds are enforced in headless collection.

$p->search('basket', 'Basket')
  ->multiple()
  ->minSelections(2) // Reject fewer than two checked.
  ->maxSelections(3) // Reject more than three checked.
  ->options([
    'apple' => 'Apple',
    'banana' => 'Banana',
    'carrot' => 'Carrot',
    'tomato' => 'Tomato',
  ]);

	ANSI	No ANSI
Unicode
ASCII

Runnable script: playground/02-widgets-search-multiple-limited.php.

Option descriptions

The highlighted match's description, in every display mode:

	ANSI	No ANSI
Unicode
ASCII

Options from a query

The options can come from the query itself rather than a fixed list, for a catalog too large to hold - see options from a query:

$p->search('veg', 'Vegetable')->optionsFrom(fn(string $query): array => $pantry->search($query));