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.

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`
`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(False, init=False)

True to show the overlay, otherwise False.

prompt `class-attribute` `instance-attribute` ¶

prompt = prompt

The prompt to show when no value is selected.

value `class-attribute` `instance-attribute` ¶

value = 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

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,
    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`
`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.

Select¶

Typing¶

Examples¶

Basic Example¶

Example using Class Method¶

Blank state¶

Reactive Attributes¶

Messages¶

Bindings¶

Component Classes¶

options ¶

prompt ¶

allow_blank ¶

value ¶

name ¶

id ¶

classes ¶

disabled ¶

tooltip ¶

BINDINGS class-attribute instance-attribute ¶

BLANK class-attribute instance-attribute ¶

expanded class-attribute instance-attribute ¶

prompt class-attribute instance-attribute ¶

value class-attribute instance-attribute ¶

Changed ¶

control property ¶

select instance-attribute ¶

value instance-attribute ¶

action_show_overlay ¶

clear ¶

from_values classmethod ¶

values ¶

prompt ¶

allow_blank ¶

value ¶

name ¶

id ¶

classes ¶

disabled ¶

is_blank ¶

set_options ¶

options ¶

EmptySelectError ¶

InvalidSelectValueError ¶

`options` ¶

`prompt` ¶

`allow_blank` ¶

`value` ¶

`name` ¶

`id` ¶

`classes` ¶

`disabled` ¶

`tooltip` ¶

BINDINGS `class-attribute` `instance-attribute` ¶

BLANK `class-attribute` `instance-attribute` ¶

expanded `class-attribute` `instance-attribute` ¶

prompt `class-attribute` `instance-attribute` ¶

value `class-attribute` `instance-attribute` ¶

control `property` ¶

select `instance-attribute` ¶

value `instance-attribute` ¶

from_values `classmethod` ¶

`values` ¶

`prompt` ¶

`allow_blank` ¶

`value` ¶

`name` ¶

`id` ¶

`classes` ¶

`disabled` ¶

`options` ¶