Interactive Prompts

Purpose and Scope

Interactive prompts are user input components that pause program execution to collect information from the terminal user. This page provides an overview of all 10 interactive prompt types available in the library, their characteristics, and guidance on selecting the appropriate prompt for different scenarios.

For implementation details of specific prompt categories, see:

• Text-based prompts: Text Input Prompts
• Selection-based prompts: Selection Prompts
• Search-based prompts: Search and Suggest Prompts
• Control flow prompts: Confirmation and Pause Prompts

For the foundational prompt lifecycle and state management that all interactive prompts share, see The Prompt Lifecycle and State Management and Validation.

Sources: High-level architecture diagrams (Diagram 2: Prompt Type Taxonomy)

---

Interactive Prompt Taxonomy

The library provides 10 interactive prompt types organized into four functional categories:

Interactive Prompt Type Hierarchy

Sources: src/helpers.php10-133 Diagram 2 from architecture overview

---

Prompt Type Comparison

Prompt Type	Helper Function	Use Case	Input Method	Return Type	Key Features
TextPrompt	text()	Single-line text input	Free-form typing	string	Placeholder, default value
TextareaPrompt	textarea()	Multi-line text input	Multi-line editing	string	Configurable row count
PasswordPrompt	password()	Sensitive text input	Masked typing	string	Hidden characters
SelectPrompt	select()	Choose one from list	Arrow key navigation	int|string	Scrolling, default selection
MultiSelectPrompt	multiselect()	Choose multiple from list	Arrow keys + spacebar	array<int|string>	Multiple defaults, scrolling
ConfirmPrompt	confirm()	Yes/No decision	Y/N or arrow keys	bool	Customizable labels
SuggestPrompt	suggest()	Text with autocomplete	Typing with suggestions	string	Static or dynamic options
SearchPrompt	search()	Choose one via search	Type to filter options	int|string	Dynamic option generation
MultiSearchPrompt	multisearch()	Choose multiple via search	Type to filter + spacebar	array<int|string>	Dynamic filtering
PausePrompt	pause()	Wait for user acknowledgment	Press Enter	bool	No input required

Sources: src/helpers.php10-133

---

Helper Function to Prompt Class Mapping

Each interactive prompt is accessible through a global helper function that instantiates the corresponding prompt class and invokes its prompt() method:

Helper Function Instantiation Pattern

Each helper function follows this pattern:

Sources: src/helpers.php40-50 src/helpers.php53-64 src/helpers.php109-119

---

Common Features Across Interactive Prompts

All interactive prompts share a consistent set of features, though not every feature is available on every prompt type:

Validation

Most prompts accept a $validate parameter that can be:

• A Closure accepting the input value and returning an error message string on failure
• A validation rule string or array (implementation-dependent)
• null to skip validation

Transformation

The $transform parameter accepts a Closure that modifies the returned value after successful submission:

Required Fields

The $required parameter controls whether empty input is allowed:

• true: Field is required (default for most prompts)
• false: Field is optional
• string: Field is required with custom error message

Note: SelectPrompt and SearchPrompt only accept true or a string, never false.

Default Values

Most prompts support default values that are pre-populated or pre-selected:

• Text prompts: Pre-fill the input field
• Selection prompts: Highlight the default option
• Multi-selection prompts: Pre-check multiple options

Hints

The $hint parameter displays additional context below the prompt label, useful for providing instructions or examples.

Sources: src/SelectPrompt.php27-36 src/helpers.php14-17 src/helpers.php47-50

---

Basic Usage Patterns

Pattern 1: Simple Text Collection

Pattern 2: Selection from Options

Pattern 3: Multiple Selection

Pattern 4: Dynamic Search

Pattern 5: Confirmation

Sources: src/helpers.php14-17 src/helpers.php47-50 src/helpers.php61-64 src/helpers.php116-119 src/helpers.php71-74

---

Scrolling Behavior in List-Based Prompts

Three prompt types utilize the Scrolling trait for viewport management when displaying long option lists:

Scrolling-Enabled Prompts

The $scroll parameter controls how many options are visible simultaneously:

When the user navigates beyond the visible window, the viewport automatically adjusts to keep the highlighted option visible.

Sources: src/SelectPrompt.php13 src/SelectPrompt.php31 src/SelectPrompt.php96-99 Diagram 5 from architecture overview

---

Key Input Handling

All interactive prompts respond to keyboard input through an event-based system. Common key bindings include:

Key(s)	Action	Applicable Prompts
Enter	Submit current value	All prompts
Ctrl+C	Cancel prompt	All prompts
↑ / ↓ / j / k	Navigate options	Select, MultiSelect, Search
Home / End / Ctrl+A / Ctrl+E	Jump to first/last	Select, MultiSelect, Search
Space	Toggle selection	MultiSelect, MultiSearch
Tab / Shift+Tab	Navigate (forward/backward)	Select prompts
Ctrl+U	Revert to previous step	Form contexts

Example key handler registration from SelectPrompt:

src/SelectPrompt.php55-62

Sources: src/SelectPrompt.php55-62

---

State Management

All interactive prompts follow the same state lifecycle, transitioning through these states:

1. Initial: Before first render
2. Active: Awaiting user input
3. Error: Validation failed, displaying error message
4. Submit: User confirmed input (Enter key)
5. Cancel: User cancelled prompt (Ctrl+C)

The prompt's state determines how it is rendered by the theme-specific renderer. For detailed information on state transitions and the rendering pipeline, see The Prompt Lifecycle and State Management and Validation.

Sources: Diagram 3 from architecture overview, Core Architecture page

---

Options Format

Selection-based and search-based prompts accept options in two formats:

Format 1: List Array (Values as Options)

Format 2: Associative Array (Keys as Values)

The SelectPrompt::value() method determines which format is in use:

src/SelectPrompt.php68-78

Options Format Detection

Sources: src/SelectPrompt.php68-78 src/SelectPrompt.php74-77

---

Hyperf Collection Support

All prompts that accept arrays also accept Hyperf\Collection\Collection instances:

Collections are automatically converted to arrays:

src/SelectPrompt.php41

Sources: src/SelectPrompt.php25 src/SelectPrompt.php41 src/helpers.php8

---

Return Values

Interactive prompts return typed values based on their purpose:

Prompt Type	Return Type	Example Values
Text-based	string	"John Doe", ""
SelectPrompt	int|string	"red" (list), 1 (associative)
MultiSelectPrompt	array<int|string>	["red", "blue"], [1, 3, 5]
ConfirmPrompt	bool	true, false
SearchPrompt	int|string	Same as SelectPrompt
MultiSearchPrompt	array<int|string>	Same as MultiSelectPrompt
PausePrompt	bool	true (continued), false (cancelled)

Sources: src/SelectPrompt.php68-78 src/helpers.php47 src/helpers.php61 src/helpers.php71

---

Non-Interactive Fallback

When running in non-interactive environments (e.g., CI pipelines), prompts automatically return default values without blocking for input. This behavior is controlled by the Prompt::$interactive static property.

For details on fallback mechanisms and environment detection, see Fallback Implementations and Interactivity.

Sources: src/SelectPrompt.php70-72

---

Next Steps

For detailed documentation of each prompt category:

• Text-based input: See Text Input Prompts for text(), textarea(), and password()
• Selection lists: See Selection Prompts for select() and multiselect()
• Dynamic searching: See Search and Suggest Prompts for search(), multisearch(), and suggest()
• Control flow: See Confirmation and Pause Prompts for confirm() and pause()

For integrating prompts into multi-step workflows, see Multi-Step Forms with FormBuilder.

Sources: Table of contents structure