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 in to 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 widget Select 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.

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.

---

textual.widgets.Select class

def __init__(
    self,
    options,
    *,
    prompt="Select",
    allow_blank=True,
    value=BLANK,
    name=None,
    id=None,
    classes=None,
    disabled=False
):

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

Parameter	Default	Description
options Iterable[tuple[RenderableType, SelectType]]	required	Options to select from. If no options are provided then allow_blank must be set to True.
prompt str	'Select'	Text to show in the control when no option is selected.
allow_blank bool	True	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.
value SelectType | NoSelection	BLANK	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.
name str | None	None	The name of the select control.
id str | None	None	The ID of the control in the DOM.
classes str | None	None	The CSS classes of the control.
disabled bool	False	Whether the control is disabled or not.

Raises

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

BINDINGS instance-attribute class-attribute

BINDINGS = [('enter,down,space,up', 'show_overlay')]

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

BLANK instance-attribute class-attribute

BLANK = BLANK

Constant to flag that the widget has no selection.

expanded instance-attribute class-attribute

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

True to show the overlay, otherwise False.

prompt instance-attribute class-attribute

prompt: var[str] = prompt

The prompt to show when no value is selected.

value instance-attribute class-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 class

def __init__(self, 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 method

def action_show_overlay(self):

Show the overlay.

clear method

def clear(self):

Clear the selection if allow_blank is True.

Raises

Type	Description
InvalidSelectValueError	If allow_blank is set to False.

from_values classmethod

def from_values(
    cls,
    values,
    *,
    prompt="Select",
    allow_blank=True,
    value=BLANK,
    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

Parameter	Default	Description
values Iterable[SelectType]	required	Values used to generate options to select from.
prompt str	'Select'	Text to show in the control when no option is selected.
allow_blank bool	True	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.
value SelectType | NoSelection	BLANK	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.
name str | None	None	The name of the select control.
id str | None	None	The ID of the control in the DOM.
classes str | None	None	The CSS classes of the control.
disabled bool	False	Whether the control is disabled or not.

Returns

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

is_blank method

def is_blank(self):

Indicates whether this Select is blank or not.

Returns

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

set_options method

def set_options(self, 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

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

Raises

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

EmptySelectError class

Bases: Exception

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

InvalidSelectValueError class

Bases: Exception

Raised when setting a Select to an unknown option.