Suggest

Free text with autocomplete over a fixed candidate set. As you type, candidates are fuzzy-matched and ranked by relevance. It's an open set - it collects a string that doesn't have to be one of the candidates.

$p->suggest('fruit', 'Fruit')
  ->options([
    'Apple' => 'Apple',
    'Apricot' => 'Apricot',
    'Banana' => 'Banana',
    'Cherry' => 'Cherry',
    'Mango' => 'Mango',
  ])
  ->default('Apple') // Initial text.
  ->pageSize(8)      // Suggestions visible before the list pages.
  ->ghost();         // Preview the leading match inline as you type.

Runnable script: playground/02-widgets-suggest.php.

Options

Name	Description	Required	Default
options()	The candidate set to autocomplete against; only the values are used.	No	None
default()	Initial text.	No	'' (empty)
pageSize()	Suggestions shown before the list pages around the cursor.	No	10
ghost()	Preview the leading prefix match as inline ghost-text.	No	false

Because the set is open, Enter accepts the highlighted suggestion, or your typed text as-is when none is highlighted. A description line can accompany the highlighted suggestion, keyed by value with ->option(..., description: ...).

Keyboard

Key	Action
printable keys	Type to filter the candidates
↑ / ↓	Highlight a suggestion
Backspace	Delete the character before the caret
Tab / →	Accept the ghost-text preview, when ghost() is on
Enter	Accept the highlighted suggestion, or the typed text if none
Esc	Cancel

Display modes

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

	ANSI	No ANSI
Unicode
ASCII

Ghost text

With ->ghost(), the highest-ranked candidate your input is a prefix of is previewed dimmed after the caret, and Tab or → accepts it. The completion becomes the new query rather than a selection, so the ranked list stays open and narrows around it.

It complements the list rather than replacing it, and it steps aside where it would mislead: the preview is suppressed once you arrow into the list (the highlighted suggestion is the value then, not your typed text), while a query source is still resolving (those candidates answer the previous query), and it only ever completes a prefix - a fuzzy hit like ga → Green apple has no inline suffix to draw. Like the Text widget's ghost text, it is suppressed when color is off.

A completion and a placeholder() share that dimmed slot and never contend for it: a completion needs a typed query, a placeholder needs an empty one.

	ANSI	No ANSI
Unicode
ASCII

Option descriptions

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

	ANSI	No ANSI
Unicode
ASCII

Suggestions from a query

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

$p->suggest('extra', 'Add another')->optionsFrom(fn(string $query): array => $pantry->search($query))->minQuery(2);