0
# Selection Prompts
1
2
Selection prompts enable users to choose from predefined options using single-choice selection, multi-choice checkboxes, or keyboard shortcut-based selection.
3
4
## Capabilities
5
6
### Single Selection
7
8
Interactive single-choice selection from a list of options with arrow key navigation, search filtering, and keyboard shortcuts.
9
10
```python { .api }
11
def select(message: str, choices: Sequence[Union[str, Choice, Dict]],
12
default: Optional[Union[str, Choice, Dict]] = None, qmark: str = "?",
13
pointer: Optional[str] = "»", style: Optional[Style] = None,
14
use_shortcuts: bool = False, use_arrow_keys: bool = True,
15
use_indicator: bool = False, use_jk_keys: bool = True,
16
use_emacs_keys: bool = True, use_search_filter: bool = False,
17
show_selected: bool = False, show_description: bool = True,
18
instruction: Optional[str] = None, **kwargs) -> Question:
19
"""
20
Create a single-choice selection prompt.
21
22
Args:
23
message: The question/prompt text to display
24
choices: List of options (strings, Choice objects, or dicts)
25
default: Default selected choice
26
qmark: Question prefix symbol (default "?")
27
pointer: Selection pointer symbol (default "»")
28
style: Custom styling configuration
29
use_shortcuts: Enable keyboard shortcuts for choices
30
use_arrow_keys: Enable up/down arrow navigation
31
use_indicator: Show selection indicator next to choices
32
use_jk_keys: Enable j/k vim-style navigation
33
use_emacs_keys: Enable Emacs-style key bindings
34
use_search_filter: Enable search/filter functionality
35
show_selected: Display selected choice after selection
36
show_description: Show choice descriptions if available
37
instruction: Additional instruction text
38
**kwargs: Additional prompt_toolkit arguments
39
40
Returns:
41
Question instance ready for execution
42
"""
43
```
44
45
### Multiple Selection (Checkbox)
46
47
Multi-choice selection prompt allowing users to select multiple options with checkbox-style indicators.
48
49
```python { .api }
50
def checkbox(message: str, choices: Sequence[Union[str, Choice, Dict]],
51
default: Optional[str] = None,
52
validate: Callable[[List[str]], Union[bool, str]] = lambda a: True,
53
qmark: str = "?", pointer: Optional[str] = "»",
54
style: Optional[Style] = None,
55
initial_choice: Optional[Union[str, Choice, Dict]] = None,
56
use_arrow_keys: bool = True, use_jk_keys: bool = True,
57
use_emacs_keys: bool = True, use_search_filter: bool = False,
58
instruction: Optional[str] = None, show_description: bool = True,
59
cycle_list: bool = True, **kwargs) -> Question:
60
"""
61
Create a multiple-choice checkbox prompt.
62
63
Args:
64
message: The question/prompt text to display
65
choices: List of options (strings, Choice objects, or dicts)
66
default: Default selected choice name
67
validate: Validation function for selected choices
68
qmark: Question prefix symbol (default "?")
69
pointer: Selection pointer symbol (default "»")
70
style: Custom styling configuration
71
initial_choice: Initially focused choice
72
use_arrow_keys: Enable up/down arrow navigation
73
use_jk_keys: Enable j/k vim-style navigation
74
use_emacs_keys: Enable Emacs-style key bindings
75
use_search_filter: Enable search/filter functionality
76
instruction: Additional instruction text
77
show_description: Show choice descriptions if available
78
cycle_list: Allow cycling through list boundaries
79
**kwargs: Additional prompt_toolkit arguments
80
81
Returns:
82
Question instance ready for execution
83
"""
84
```
85
86
### Raw Selection (Keyboard Shortcuts)
87
88
Single-choice selection using only keyboard shortcuts without arrow key navigation.
89
90
```python { .api }
91
def rawselect(message: str, choices: Sequence[Union[str, Choice, Dict]],
92
default: Optional[str] = None, qmark: str = "?",
93
pointer: Optional[str] = "»", style: Optional[Style] = None,
94
**kwargs) -> Question:
95
"""
96
Create a keyboard shortcut-based selection prompt.
97
98
Args:
99
message: The question/prompt text to display
100
choices: List of options (strings, Choice objects, or dicts)
101
default: Default selected choice
102
qmark: Question prefix symbol (default "?")
103
pointer: Selection pointer symbol (default "»")
104
style: Custom styling configuration
105
**kwargs: Additional prompt_toolkit arguments
106
107
Returns:
108
Question instance ready for execution
109
"""
110
```
111
112
## Choice Configuration
113
114
### Choice Objects
115
116
Advanced choice configuration with custom values, descriptions, and states.
117
118
```python { .api }
119
class Choice:
120
def __init__(self, title: FormattedText, value: Optional[Any] = None,
121
disabled: Optional[str] = None, checked: Optional[bool] = False,
122
shortcut_key: Optional[Union[str, bool]] = True,
123
description: Optional[str] = None) -> None:
124
"""
125
Configure a choice for selection prompts.
126
127
Args:
128
title: Display text for the choice
129
value: Return value when choice is selected (defaults to title)
130
disabled: Reason text if choice is disabled (None = enabled)
131
checked: Initially selected state for checkbox prompts
132
shortcut_key: Keyboard shortcut (True = auto-generate, False = none)
133
description: Additional description text
134
"""
135
136
@staticmethod
137
def build(c: Union[str, Choice, Dict]) -> Choice:
138
"""
139
Build Choice from string, existing Choice, or dictionary.
140
141
Args:
142
c: Choice specification
143
144
Returns:
145
Choice instance
146
"""
147
```
148
149
### Separator Objects
150
151
Visual separators for organizing choice lists.
152
153
```python { .api }
154
class Separator(Choice):
155
def __init__(self, line: Optional[str] = None) -> None:
156
"""
157
Create a visual separator for choice lists.
158
159
Args:
160
line: Custom separator text (default: 15 dashes)
161
"""
162
```
163
164
## Usage Examples
165
166
### Basic Selection
167
168
```python
169
import questionary
170
171
# Simple string choices
172
color = questionary.select(
173
"Choose a color:",
174
choices=["Red", "Green", "Blue"]
175
).ask()
176
177
# With default selection
178
size = questionary.select(
179
"Choose size:",
180
choices=["Small", "Medium", "Large"],
181
default="Medium"
182
).ask()
183
```
184
185
### Advanced Choice Configuration
186
187
```python
188
import questionary
189
from questionary import Choice, Separator
190
191
# Using Choice objects with custom values
192
action = questionary.select(
193
"What would you like to do?",
194
choices=[
195
Choice("Create new project", value="create"),
196
Choice("Open existing project", value="open"),
197
Choice("Delete project", value="delete", disabled="Not implemented"),
198
Separator(),
199
Choice("Exit", value="exit")
200
]
201
).ask()
202
203
# Choices with descriptions
204
framework = questionary.select(
205
"Choose framework:",
206
choices=[
207
Choice("Django", description="Full-featured web framework"),
208
Choice("Flask", description="Lightweight WSGI framework"),
209
Choice("FastAPI", description="Modern async web framework")
210
],
211
show_description=True
212
).ask()
213
```
214
215
### Checkbox (Multiple Selection)
216
217
```python
218
import questionary
219
220
# Basic checkbox selection
221
toppings = questionary.checkbox(
222
"Select pizza toppings:",
223
choices=["Cheese", "Pepperoni", "Mushrooms", "Olives", "Peppers"]
224
).ask()
225
226
# With validation requiring at least one selection
227
def validate_selection(answers):
228
if len(answers) == 0:
229
return "Please select at least one option"
230
return True
231
232
services = questionary.checkbox(
233
"Which services to enable?",
234
choices=["Database", "Cache", "Queue", "Storage"],
235
validate=validate_selection
236
).ask()
237
238
# Pre-checked options
239
features = questionary.checkbox(
240
"Select features:",
241
choices=[
242
Choice("Authentication", checked=True),
243
Choice("API Documentation", checked=True),
244
Choice("Admin Panel", checked=False),
245
Choice("Email Service", checked=False)
246
]
247
).ask()
248
```
249
250
### Raw Selection with Shortcuts
251
252
```python
253
import questionary
254
255
# Automatic shortcut generation
256
priority = questionary.rawselect(
257
"Select priority:",
258
choices=["High", "Medium", "Low"]
259
).ask()
260
261
# Custom shortcuts
262
environment = questionary.rawselect(
263
"Deploy to:",
264
choices=[
265
Choice("Development", shortcut_key="d"),
266
Choice("Staging", shortcut_key="s"),
267
Choice("Production", shortcut_key="p")
268
]
269
).ask()
270
```
271
272
### Search and Filtering
273
274
```python
275
import questionary
276
277
# Enable search functionality
278
country = questionary.select(
279
"Select country:",
280
choices=["United States", "Canada", "United Kingdom", "Germany", "France", "Japan"],
281
use_search_filter=True,
282
instruction="Type to filter options"
283
).ask()
284
```
285
286
### Keyboard Navigation Options
287
288
```python
289
import questionary
290
291
# Customize navigation keys
292
option = questionary.select(
293
"Choose option:",
294
choices=["Option 1", "Option 2", "Option 3"],
295
use_arrow_keys=True, # Up/down arrows
296
use_jk_keys=True, # j/k vim-style
297
use_emacs_keys=True, # Emacs bindings
298
use_shortcuts=True # Number shortcuts
299
).ask()
300
```