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',
  ]);