OptionList

Added in version 0.17.0

A widget for showing a vertical list of Rich renderable options.

• Focusable
• Container

Examples

Options as simple strings

An OptionList can be constructed with a simple collection of string options:

Outputoption_list_strings.pyoption_list.tcss

from textual.app import App, ComposeResult
from textual.widgets import Footer, Header, OptionList


class OptionListApp(App[None]):
    CSS_PATH = "option_list.tcss"

    def compose(self) -> ComposeResult:
        yield Header()
        yield OptionList(
            "Aerilon",
            "Aquaria",
            "Canceron",
            "Caprica",
            "Gemenon",
            "Leonis",
            "Libran",
            "Picon",
            "Sagittaron",
            "Scorpia",
            "Tauron",
            "Virgon",
        )
        yield Footer()


if __name__ == "__main__":
    OptionListApp().run()

Screen {
    align: center middle;
}

OptionList {
    width: 70%;
    height: 80%;
}

Options as Option instances

For finer control over the options, the Option class can be used; this allows for setting IDs, setting initial disabled state, etc. The Separator class can be used to add separator lines between options.

Outputoption_list_options.pyoption_list.tcss

from textual.app import App, ComposeResult
from textual.widgets import Footer, Header, OptionList
from textual.widgets.option_list import Option


class OptionListApp(App[None]):
    CSS_PATH = "option_list.tcss"

    def compose(self) -> ComposeResult:
        yield Header()
        yield OptionList(
            Option("Aerilon", id="aer"),
            Option("Aquaria", id="aqu"),
            None,
            Option("Canceron", id="can"),
            Option("Caprica", id="cap", disabled=True),
            None,
            Option("Gemenon", id="gem"),
            None,
            Option("Leonis", id="leo"),
            Option("Libran", id="lib"),
            None,
            Option("Picon", id="pic"),
            None,
            Option("Sagittaron", id="sag"),
            Option("Scorpia", id="sco"),
            None,
            Option("Tauron", id="tau"),
            None,
            Option("Virgon", id="vir"),
        )
        yield Footer()


if __name__ == "__main__":
    OptionListApp().run()

Screen {
    align: center middle;
}

OptionList {
    width: 70%;
    height: 80%;
}

Options as Rich renderables

Because the prompts for the options can be Rich renderables, this means they can be any height you wish. As an example, here is an option list comprised of Rich tables:

Outputoption_list_tables.pyoption_list.tcss

from __future__ import annotations

from rich.table import Table

from textual.app import App, ComposeResult
from textual.widgets import Footer, Header, OptionList

COLONIES: tuple[tuple[str, str, str, str], ...] = (
    ("Aerilon", "Demeter", "1.2 Billion", "Gaoth"),
    ("Aquaria", "Hermes", "75,000", "None"),
    ("Canceron", "Hephaestus", "6.7 Billion", "Hades"),
    ("Caprica", "Apollo", "4.9 Billion", "Caprica City"),
    ("Gemenon", "Hera", "2.8 Billion", "Oranu"),
    ("Leonis", "Artemis", "2.6 Billion", "Luminere"),
    ("Libran", "Athena", "2.1 Billion", "None"),
    ("Picon", "Poseidon", "1.4 Billion", "Queenstown"),
    ("Sagittaron", "Zeus", "1.7 Billion", "Tawa"),
    ("Scorpia", "Dionysus", "450 Million", "Celeste"),
    ("Tauron", "Ares", "2.5 Billion", "Hypatia"),
    ("Virgon", "Hestia", "4.3 Billion", "Boskirk"),
)


class OptionListApp(App[None]):
    CSS_PATH = "option_list.tcss"

    @staticmethod
    def colony(name: str, god: str, population: str, capital: str) -> Table:
        table = Table(title=f"Data for {name}", expand=True)
        table.add_column("Patron God")
        table.add_column("Population")
        table.add_column("Capital City")
        table.add_row(god, population, capital)
        return table

    def compose(self) -> ComposeResult:
        yield Header()
        yield OptionList(*[self.colony(*row) for row in COLONIES])
        yield Footer()


if __name__ == "__main__":
    OptionListApp().run()

Screen {
    align: center middle;
}

OptionList {
    width: 70%;
    height: 80%;
}

Reactive Attributes

Name	Type	Default	Description
highlighted	int | None	None	The index of the highlighted option. None means nothing is highlighted.

Messages

• OptionList.OptionHighlighted
• OptionList.OptionSelected

Both of the messages above inherit from the common base OptionList.OptionMessage, so refer to its documentation to see what attributes are available.

Bindings

The option list widget defines the following bindings:

Key(s)	Description
down	Move the highlight down.
end	Move the highlight to the last option.
enter	Select the current option.
home	Move the highlight to the first option.
pagedown	Move the highlight down a page of options.
pageup	Move the highlight up a page of options.
up	Move the highlight up.

Component Classes

The option list provides the following component classes:

Class	Description
option-list--option	Target options that are not disabled, highlighted or have the mouse over them.
option-list--option-disabled	Target disabled options.
option-list--option-highlighted	Target the highlighted option.
option-list--option-hover	Target an option that has the mouse over it.
option-list--separator	Target the separators.

Bases: ScrollView

A navigable list of options.

Parameters:

Name	Type	Description	Default
*content	OptionListContent	Positional arguments become the options.	()
name	str | None	Name of the OptionList.	None
id	str | None	The ID of the OptionList in the DOM.	None
classes	str | None	Initial CSS classes.	None
disabled	bool	Disable the widget?	False
markup	bool	Strips should be rendered as content markup if True, or plain text if False.	True
compact	bool	Enable compact style?	False

BINDINGS class-attribute

BINDINGS = [
    Binding("down", "cursor_down", "Down", show=False),
    Binding("end", "last", "Last", show=False),
    Binding("enter", "select", "Select", show=False),
    Binding("home", "first", "First", show=False),
    Binding(
        "pagedown", "page_down", "Page Down", show=False
    ),
    Binding("pageup", "page_up", "Page Up", show=False),
    Binding("up", "cursor_up", "Up", show=False),
]

Key(s)	Description
down	Move the highlight down.
end	Move the highlight to the last option.
enter	Select the current option.
home	Move the highlight to the first option.
pagedown	Move the highlight down a page of options.
pageup	Move the highlight up a page of options.
up	Move the highlight up.

COMPONENT_CLASSES class-attribute

COMPONENT_CLASSES = {
    "option-list--option",
    "option-list--option-disabled",
    "option-list--option-highlighted",
    "option-list--option-hover",
    "option-list--separator",
}

Class	Description
option-list--option	Target options that are not disabled, highlighted or have the mouse over them.
option-list--option-disabled	Target disabled options.
option-list--option-highlighted	Target the highlighted option.
option-list--option-hover	Target an option that has the mouse over it.
option-list--separator	Target the separators.

compact class-attribute instance-attribute

compact = compact

Enable compact display?

highlighted class-attribute instance-attribute

highlighted = reactive(None)

The index of the currently-highlighted option, or None if no option is highlighted.

highlighted_option property

highlighted_option

The currently highlighted option, or None if no option is highlighted.

Returns:

Type	Description
Option | None	An Option, or None.

option_count property

option_count

The number of options.

options property