Skip to content

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.

SelectApp SelectApp ▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔ Select ▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁

SelectApp SelectApp ▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔ Select ▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁ ▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔ Select 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. ▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁

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.

SelectApp SelectApp ▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔ Select ▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁

SelectApp SelectApp ▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔ Select ▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁ ▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔ Select 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. ▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁

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

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)

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.