Selection Prompts

Purpose and Scope

This document covers the two selection prompt types in the hypervel/prompts library: select and multiselect. These prompts present users with a predefined list of options and allow them to choose one or multiple values through keyboard navigation.

• Select prompts (SelectPrompt) allow users to choose exactly one option from a list
• Multi-select prompts (MultiSelectPrompt) allow users to choose zero or more options from a list

Both prompt types use the Scrolling trait to handle list navigation. For search-enabled selection prompts with dynamic filtering, see page 5.3. For information about the underlying scrolling mechanism, see page 9.1.

Overview

Selection prompts display a list of options and allow users to navigate using keyboard controls. The prompts automatically handle viewport scrolling for long lists, displaying only a subset of options at a time while allowing users to scroll through the full list.

Helper Function to Class Mapping

Sources: src/helpers.php40-65 src/SelectPrompt.php11-13 src/MultiSelectPrompt.php10-12

Select Prompt

The SelectPrompt class provides single-option selection from a predefined list. Users navigate with arrow keys and submit their choice with Enter.

Function Signature

The select() helper function creates a SelectPrompt instance:

Sources: src/helpers.php40-51

Parameters

Parameter	Type	Default	Description
$label	string	-	The prompt question or label displayed to the user
$options	array|Collection	-	The options to choose from (see Option Formats below)
$default	int|string|null	null	The default selected value or key
$scroll	int	5	Number of options visible at once before scrolling
$validate	mixed	null	Validation callback or rules
$hint	string	''	Help text displayed below the prompt
$required	bool|string	true	Must be true or a custom error message (cannot be false)
$transform	?Closure	null	Transform the returned value before returning

Important: The $required parameter cannot be false for select prompts. An exception is thrown if false is provided, as a selection is always expected.

Sources: src/SelectPrompt.php27-39 src/helpers.php40-51

Option Formats and Return Values

SelectPrompt supports two option array formats, which affect what value is returned:

List Arrays (Indexed)

When options are provided as a simple indexed array, the selected value itself is returned:

Associative Arrays (Key-Value)

When options are provided as an associative array, the selected key is returned:

The distinction is determined by the array_is_list() check in src/SelectPrompt.php74-77

Sources: src/SelectPrompt.php68-78 src/SelectPrompt.php83-89

Default Value Handling

When a default value is provided, the prompt initializes with that option highlighted. The logic differs based on array format:

• List arrays: Searches for the value itself in the options array src/SelectPrompt.php44-45
• Associative arrays: Searches for the key in the array keys src/SelectPrompt.php47

After finding the default position, the viewport scrolls to ensure it's visible src/SelectPrompt.php50

Sources: src/SelectPrompt.php43-53

Key Bindings

SelectPrompt supports extensive keyboard navigation:

Key(s)	Action
↑, ←, Shift+Tab, Ctrl+P, Ctrl+B, k, h	Move highlight to previous option
↓, →, Tab, Ctrl+N, Ctrl+F, j, l	Move highlight to next option
Home, Ctrl+A	Jump to first option
End, Ctrl+E	Jump to last option
Enter	Submit selected option

Sources: src/SelectPrompt.php55-62

Keyboard Navigation Flow

Sources: src/SelectPrompt.php55-62

Multi-Select Prompt

The MultiSelectPrompt class allows users to select zero or more options from a list. Users toggle individual options with the spacebar and submit their selections with Enter.

Function Signature

The multiselect() helper function creates a MultiSelectPrompt instance:

Sources: src/helpers.php53-65

Parameters

Parameter	Type	Default	Description
$label	string	-	The prompt question or label displayed to the user
$options	array|Collection	-	The options to choose from
$default	array|Collection	[]	Array of default selected values or keys
$scroll	int	5	Number of options visible at once before scrolling
$required	bool|string	false	Whether at least one selection is required
$validate	mixed	null	Validation callback or rules
$hint	string	'Use the space bar...'	Help text displayed below the prompt
$transform	?Closure	null	Transform the returned array before returning

Key Differences from Select:

• Returns an array instead of a single value
• $required defaults to false (selections are optional)
• Default hint text instructs users about the spacebar
• $default is an array of multiple values

Sources: src/MultiSelectPrompt.php41-50 src/helpers.php53-65

Return Value

MultiSelectPrompt always returns an array of selected values. The format depends on the option array structure:

• List arrays: Returns the selected values themselves
• Associative arrays: Returns the selected keys

The value() method returns array_values() to ensure a clean numeric array without key gaps src/MultiSelectPrompt.php74-77

Sources: src/MultiSelectPrompt.php33 src/MultiSelectPrompt.php74-77

Selection State Management

MultiSelectPrompt maintains three key state variables:

Property	Type	Purpose
$options	array	All available options
$default	array	Initial default selections
$values	array	Currently selected values (mutable)

The $values array is initialized with $default src/MultiSelectPrompt.php53 and is modified as users toggle selections.

Sources: src/MultiSelectPrompt.php19-33 src/MultiSelectPrompt.php51-53

Key Bindings

MultiSelectPrompt extends the navigation keys with selection toggles:

Key(s)	Action
↑, ←, Shift+Tab, Ctrl+P, Ctrl+B, k, h	Move highlight to previous option
↓, →, Tab, Ctrl+N, Ctrl+F, j, l	Move highlight to next option
Home	Jump to first option
End	Jump to last option
Space	Toggle selection of highlighted option
Ctrl+A	Toggle all options (select all / deselect all)
Enter	Submit current selections

Sources: src/MultiSelectPrompt.php57-66

Toggle Behavior

Individual Toggle (Space)

The toggleHighlighted() method adds or removes the currently highlighted option from the $values array:

1. Determines the value (item for list arrays, key for associative arrays) src/MultiSelectPrompt.php142-144
2. If already selected, removes it from $values src/MultiSelectPrompt.php146-147
3. If not selected, appends it to $values src/MultiSelectPrompt.php148-149

Sources: src/MultiSelectPrompt.php140-151

Toggle All (Ctrl+A)

The toggleAll() method implements "select all" or "deselect all" functionality:

1. If all options are currently selected, clears $values to empty array src/MultiSelectPrompt.php128-129
2. Otherwise, selects all options (values for list arrays, keys for associative arrays) src/MultiSelectPrompt.php130-133

Sources: src/MultiSelectPrompt.php126-135

Helper Methods

MultiSelectPrompt provides methods to check selection and highlight state:

isHighlighted(string $value): bool

Returns whether the given value/key is currently highlighted (cursor position). Used by renderers to apply highlight styling src/MultiSelectPrompt.php106-113

isSelected(string $value): bool

Returns whether the given value/key is currently selected (checked). Used by renderers to display checkmarks or other selection indicators src/MultiSelectPrompt.php118-121

labels(): array

Returns the display labels (not keys) of selected items. For list arrays, returns the values themselves. For associative arrays, looks up the labels from the options array src/MultiSelectPrompt.php84-91

visible(): array

Returns the currently visible subset of options based on scroll position. Used by renderers to display only the viewport portion of the list src/MultiSelectPrompt.php98-101

Sources: src/MultiSelectPrompt.php84-101 src/MultiSelectPrompt.php106-121

Scrolling Integration

Both SelectPrompt and MultiSelectPrompt use the Scrolling trait to manage list navigation with the following properties:

• $highlighted: Index of the currently highlighted option
• $firstVisible: Index of the first visible option in the viewport
• $scroll: Number of options to display at once

The trait provides methods like highlightPrevious(), highlightNext(), and scrollToHighlighted() that handle viewport updates automatically. See page 9.1 for detailed documentation of this mechanism.

Sources: src/SelectPrompt.php13 src/MultiSelectPrompt.php12

Common Patterns

Option Array Architecture

Sources: src/SelectPrompt.php41-42 src/MultiSelectPrompt.php51-52

Comparison: Select vs MultiSelect

Feature	SelectPrompt	MultiSelectPrompt
Return type	int|string	array
Default $required	true	false
Default $hint	Empty string	"Use the space bar to select options."
Selection mechanism	Automatic on highlight	Toggle with Space
Select all support	No	Yes (Ctrl+A)
State storage	Position only ($highlighted)	Position + selections ($values)
Primary use case	Single choice required	Multiple optional choices

Sources: src/SelectPrompt.php27-36 src/MultiSelectPrompt.php41-49