Skip to content


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.


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)


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.


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 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.css"

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

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

if __name__ == "__main__":
    app = SelectApp()
Screen {
    align: center top;

Select {
    width: 60;
    margin: 2;


Reactive attributes

Name Type Default Description
expanded bool False True to expand the options overlay.
value SelectType | None None Current value of the Select.


The Select widget defines the following bindings:

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

textual.widgets.Select class

def __init__(

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.

Name Type Description Default
options Iterable[tuple[str, SelectType]]

Options to select from.

prompt str

Text to show in the control when no option is select.

allow_blank bool

Allow the selection of a blank option.

value SelectType | None

Initial value (should be one of the values in options).

name str | None

The name of the select control.

id str | None

The ID of the control the DOM.

classes str | None

The CSS classes of the control.

disabled bool

Whether the control is disabled or not.


BINDINGS class-attribute instance-attribute

BINDINGS = [('enter,down,space,up', 'show_overlay')]
Key(s) Description
enter,down,space,up Activate the overlay

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.

value class-attribute instance-attribute

value: var[SelectType | None] = var[Optional[SelectType]](

The value of the select.

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

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.

compose method

def compose(self):

Compose Select with overlay and current value.

set_options method

def set_options(self, options):

Set the options for the Select.

Name Type Description Default
options Iterable[tuple[RenderableType, SelectType]]

An iterable of tuples containing (STRING, VALUE).