1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
|
# Select
!!! tip "Added in version 0.24.0"
A Select widget is a compact control to allow the user to select between a number of possible options.
- [X] Focusable
- [ ] Container
The options in a select control may be passed into the constructor or set later with [set_options][textual.widgets.Select.set_options].
Options should be given as a sequence of tuples consisting of two values: the first is the string (or [Rich Renderable](https://rich.readthedocs.io/en/latest/protocol.html)) to display in the control and list of options, the second is the value of option.
The value of the currently selected option is stored in the `value` attribute of the widget, and the `value` attribute of the [Changed][textual.widgets.Select.Changed] message.
## Typing
The `Select` control is a typing Generic which allows you to set the type of the option values.
For instance, if the data type for your values is an integer, you would type the widget as follows:
```python
options = [("First", 1), ("Second", 2)]
my_select: Select[int] = Select(options)
```
!!! note
Typing is entirely optional.
If you aren't familiar with typing or don't want to worry about it right now, feel free to ignore it.
## Examples
### Basic Example
The following example presents a `Select` with a number of options.
=== "Output"
```{.textual path="docs/examples/widgets/select_widget.py"}
```
=== "Output (expanded)"
```{.textual path="docs/examples/widgets/select_widget.py" press="tab,enter,down,down"}
```
=== "select_widget.py"
```python
--8<-- "docs/examples/widgets/select_widget.py"
```
=== "select.tcss"
```css
--8<-- "docs/examples/widgets/select.tcss"
```
### Example using Class Method
The following example presents a `Select` created using the `from_values` class method.
=== "Output"
```{.textual path="docs/examples/widgets/select_from_values_widget.py"}
```
=== "Output (expanded)"
```{.textual path="docs/examples/widgets/select_from_values_widget.py" press="tab,enter,down,down"}
```
=== "select_from_values_widget.py"
```python
--8<-- "docs/examples/widgets/select_from_values_widget.py"
```
=== "select.tcss"
```css
--8<-- "docs/examples/widgets/select.tcss"
```
## Blank state
The `Select` widget has an option `allow_blank` for its constructor.
If set to `True`, the widget may be in a state where there is no selection, in which case its value will be the special constant [`Select.BLANK`][textual.widgets.Select.BLANK].
The auxiliary methods [`Select.is_blank`][textual.widgets.Select.is_blank] and [`Select.clear`][textual.widgets.Select.clear] provide a convenient way to check if the widget is in this state and to set this state, respectively.
## Type to search
The `Select` widget has a `type_to_search` attribute which allows you to type to move the cursor to a matching option when the widget is expanded. To disable this behavior, set the attribute to `False`.
## Reactive Attributes
| Name | Type | Default | Description |
|------------|--------------------------------|------------------------------------------------|-------------------------------------|
| `expanded` | `bool` | `False` | True to expand the options overlay. |
| `value` | `SelectType` \| `_NoSelection` | [`Select.BLANK`][textual.widgets.Select.BLANK] | Current value of the Select. |
## Messages
- [Select.Changed][textual.widgets.Select.Changed]
## Bindings
The Select widget defines the following bindings:
::: textual.widgets.Select.BINDINGS
options:
show_root_heading: false
show_root_toc_entry: false
## Component Classes
This widget has no component classes.
---
::: textual.widgets.Select
options:
heading_level: 2
::: textual.widgets.select
options:
heading_level: 2
|
