Select

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.

• Focusable
• Container

The options in a select control may be passed into the constructor or set later with set_options. Options should be given as a sequence of tuples consisting of two values: the first is the string (or Rich Renderable) 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 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:

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.

OutputOutput (expanded)select_widget.pyselect.tcss

from textual import on
from textual.app import App, ComposeResult
from textual.widgets import Header, Select

LINES = """I must not fear.
Fear is the mind-killer.
Fear is the little-death that brings total obliteration.
I will face my fear.
I will permit it to pass over me and through me.""".splitlines()


class SelectApp(App):
    CSS_PATH = "select.tcss"

    def compose(self) -> ComposeResult:
        yield Header()
        yield Select((line, line) for line in LINES)

    @on(Select.Changed)
    def select_changed(self, event: Select.Changed) -> None:
        self.title = str(event.value)


if __name__ == "__main__":
    app = SelectApp()
    app.run()

Screen {
    align: center top;
}

Select {
    width: 60;
    margin: 2;
}

Example using Class Method

The following example presents a Select created using the from_values class method.

OutputOutput (expanded)select_from_values_widget.pyselect.tcss

from textual import on
from textual.app import App, ComposeResult
from textual.widgets import Header, Select

LINES = """I must not fear.
Fear is the mind-killer.
Fear is the little-death that brings total obliteration.
I will face my fear.
I will permit it to pass over me and through me.""".splitlines()


class SelectApp(App):
    CSS_PATH = "select.tcss"

    def compose(self) -> ComposeResult:
        yield Header()
        yield Select.from_values(LINES)

    @on(Select.Changed)
    def select_changed(self, event: Select.Changed) -> None:
        self.title = str(event.value)


if __name__ == "__main__":
    app = SelectApp()
    app.run()

Screen {
    align: center top;
}

Select {
    width: 60;
    margin: 2;
}

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. The auxiliary methods Select.is_blank and 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	Current value of the Select.

Messages

• Select.Changed

Bindings

The Select widget defines the following bindings:

Key(s)	Description
enter,down,space,up	Activate the overlay

Component Classes

This widget has no component classes.

---

Bases: Generic[SelectType], Vertical

Widget to select from a list of possible options.

A Select displays the current selection. When activated with Enter the widget displays an overlay with a list of all possible options.

Parameters:

Name	Type	Description	Default
options	Iterable[tuple[RenderableType, SelectType]]	Options to select from. If no options are provided then allow_blank must be set to True.	required
prompt	str	Text to show in the control when no option is selected.	'Select'
allow_blank	bool	Enables or disables the ability to have the widget in a state with no selection made, in which case its value is set to the constant Select.BLANK.	True
value	SelectType | NoSelection	Initial value selected. Should be one of the values in options. If no initial value is set and allow_blank is False, the widget will auto-select the first available option.	BLANK
type_to_search	bool	If True, typing will search for options.	True
name	str | None	The name of the select control.	None
id	str | None	The ID of the control in the DOM.	None
classes	str | None	The CSS classes of the control.	None
disabled	bool	Whether the control is disabled or not.	False
tooltip	RenderableType | None	Optional tooltip.	None

Raises:

Type	Description
EmptySelectError	If no options are provided and allow_blank is False.

BINDINGS class-attribute instance-attribute

BINDINGS = [
    Binding(
        "enter,down,space,up",
        "show_overlay",
        "Show menu",
        show=False,
    )
]

Key(s)	Description
enter,down,space,up	Activate the overlay

BLANK class-attribute instance-attribute

BLANK = BLANK

Constant to flag that the widget has no selection.

expanded class-attribute instance-attribute

expanded: var[bool] = var(False, init=False)

True to show the overlay, otherwise False.

prompt class-attribute instance-attribute

prompt: var[str] = prompt

The prompt to show when no value is selected.

selection property

selection: SelectType | None

The currently selected item.

Unlike value, this will not return Blanks. If nothing is selected, this will return None.

value class-attribute instance-attribute

value: var[SelectType | NoSelection] = var[
    Union[SelectType, NoSelection]
](BLANK, init=False)

The value of the selection.

If the widget has no selection, its value will be Select.BLANK. Setting this to an illegal value will raise a InvalidSelectValueError exception.

Changed

Changed(select, value)

Bases: Message

Posted when the select value was changed.

This message can be handled using a on_select_changed method.

control property

control: Select[SelectType]

The Select that sent the message.

select instance-attribute

select = select

The select widget.

value instance-attribute

value = value

The value of the Select when it changed.

action_show_overlay

action_show_overlay()

Show the overlay.

clear

clear()

Clear the selection if allow_blank is True.

Raises:

Type	Description
InvalidSelectValueError	If allow_blank is set to False.

from_values classmethod

from_values(
    values,
    *,
    prompt="Select",
    allow_blank=True,
    value=BLANK,
    type_to_search=True,
    name=None,
    id=None,
    classes=None,
    disabled=False
)

Initialize the Select control with values specified by an arbitrary iterable

The options shown in the control are computed by calling the built-in str on each value.

Parameters:

Name	Type	Description	Default
values	Iterable[SelectType]	Values used to generate options to select from.	required
prompt	str	Text to show in the control when no option is selected.	'Select'
allow_blank	bool	Enables or disables the ability to have the widget in a state with no selection made, in which case its value is set to the constant Select.BLANK.	True
value	SelectType | NoSelection	Initial value selected. Should be one of the values in values. If no initial value is set and allow_blank is False, the widget will auto-select the first available value.	BLANK
type_to_search	bool	If True, typing will search for options.	True
name	str | None	The name of the select control.	None
id	str | None	The ID of the control in the DOM.	None
classes	str | None	The CSS classes of the control.	None
disabled	bool	Whether the control is disabled or not.	False

Returns:

Type	Description
Select[SelectType]	A new Select widget with the provided values as options.

is_blank

is_blank()

Indicates whether this Select is blank or not.

Returns:

Type	Description
bool	True if the selection is blank, False otherwise.

set_options

set_options(options)

Set the options for the Select.

This will reset the selection. The selection will be empty, if allowed, otherwise the first valid option is picked.

Parameters:

Name	Type	Description	Default
options	Iterable[tuple[RenderableType, SelectType]]	An iterable of tuples containing the renderable to display for each option and the corresponding internal value.	required

Raises:

Type	Description
EmptySelectError	If the options iterable is empty and allow_blank is False.

EmptySelectError

Bases: Exception

Raised when a Select has no options and allow_blank=False.

InvalidSelectValueError

Bases: Exception

Raised when setting a Select to an unknown option.