Select

final class Phui\Components\Select

A trigger showing the chosen label, which opens a floating list where one option is picked. The trigger takes focus; opening it raises a modal layer anchored beneath, which holds focus while open and hands it back on close.

selected is an index into items, or null for nothing chosen.

use Phui\Components\Select;
use Phui\Events\EmitEvent;

Select::mount()
    ->props(items: $this->branches, selected: $this->branch)
    ->on('change', fn (EmitEvent $e) => $this->branch = $e->data);

Props

Prop	Type	Default	Description
items	string[]	[]	The options to list.
placeholder	string	'Select…'	Shown on the trigger while nothing is selected.
maxHeight	int	10	Options visible before the list scrolls.
accent	string	'|'	The marker at the head of the trigger.
selectedChar	string	'✓'	Marker beside the chosen option.
unselectedChar	string	' '	Marker beside every other option.
hoveredChar	string	'→'	Marker beside the option under the cursor.
unhoveredChar	string	' '	Marker beside every other option.

Models

The component holds this and emits on every change. Pass it as a prop to take ownership, and handle its emit — see binding a value both ways.

Model	Type	Default	Emits
selected	?int	null	change

Emits

Event	Payload	Emitted when
change	int	An option is chosen.

Input

Input	Action
Enter	Open the list
Left click	Open the list

While the list is open:

Input	Action
↑ k	Previous option
↓ j	Next option
Enter Space	Choose the option and close
Esc	Close without choosing
Left click	Choose the clicked option and close

Colours

Phui\Components\Colours\SelectColours

Colour	Palette default	Used for
value	text	The trigger label at rest.
valueFocused	accent	The trigger label while focused.
marker	muted	The trigger accent with nothing selected, and unchosen option markers.
markerActive	accent	The trigger accent with a selection, the chosen option's marker, and the list border.
option	text	Options in the list.
optionHighlighted	accent	The option under the cursor.