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

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


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

    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 {
    background: $panel;
    border: round $primary;
    width: 70%;
    height: 70%;
}

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

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


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

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


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

Screen {
    align: center middle;
}

OptionList {
    background: $panel;
    border: round $primary;
    width: 70%;
    height: 70%;
}

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

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

    @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 {
    background: $panel;
    border: round $primary;
    width: 70%;
    height: 70%;
}

Reactive Attributes¶

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

Both of the messages above inherit from the common base OptionList, 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.
page_down	Move the highlight down a page of options.
page_up	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-disabled`	Target disabled options.
`option-list--option-highlighted`	Target the highlighted option.
`option-list--option-highlighted-disabled`	Target a disabled option that is also highlighted.
`option-list--option-hover`	Target an option that has the mouse over it.
`option-list--option-hover-disabled`	Target a disabled option that has the mouse over it.
`option-list--option-hover-highlighted`	Target a highlighted option that has the mouse over it.
`option-list--option-hover-highlighted-disabled`	Target a disabled highlighted option that has the mouse over it.
`option-list--separator`	Target the separators.

textual.widgets.OptionList `class` ¶

def __init__(
    self,
    *content,
    name=None,
    id=None,
    classes=None,
    disabled=False
):

Bases: ScrollView

A vertical option list with bounce-bar highlighting.

Parameters

Name	Type	Description	Default
`*content`	`NewOptionListContent`	The content for the option list.	`()`
`name`	`str \| None`	The name of the option list.	`None`
`id`	`str \| None`	The ID of the option list in the DOM.	`None`
`classes`	`str \| None`	The CSS classes of the option list.	`None`
`disabled`	`bool`	Whether the option list is disabled or not.	`False`

BINDINGS `class-attribute` ¶

BINDINGS: list[BindingType] = [
    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(
        "page_down", "page_down", "Page Down", show=False
    ),
    Binding("page_up", "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.
page_down	Move the highlight down a page of options.
page_up	Move the highlight up a page of options.
up	Move the highlight up.

COMPONENT_CLASSES `class-attribute` ¶

COMPONENT_CLASSES: set[str] = {
    "option-list--option",
    "option-list--option-disabled",
    "option-list--option-highlighted",
    "option-list--option-highlighted-disabled",
    "option-list--option-hover",
    "option-list--option-hover-disabled",
    "option-list--option-hover-highlighted",
    "option-list--option-hover-highlighted-disabled",
    "option-list--separator",
}

Class	Description
`option-list--option-disabled`	Target disabled options.
`option-list--option-highlighted`	Target the highlighted option.
`option-list--option-highlighted-disabled`	Target a disabled option that is also highlighted.
`option-list--option-hover`	Target an option that has the mouse over it.
`option-list--option-hover-disabled`	Target a disabled option that has the mouse over it.
`option-list--option-hover-highlighted`	Target a highlighted option that has the mouse over it.
`option-list--option-hover-highlighted-disabled`	Target a disabled highlighted option that has the mouse over it.
`option-list--separator`	Target the separators.

DEFAULT_CSS `class-attribute` `instance-attribute` ¶

DEFAULT_CSS = "\n    OptionList {\n        background: $panel-lighten-1;\n        color: $text;\n        overflow-x: hidden;\n    }\n\n    OptionList > .option-list--separator {\n        color: $foreground 15%;\n    }\n\n    OptionList > .option-list--option-highlighted {\n        background: $accent 50%;\n        color: $text;\n        text-style: bold;\n    }\n\n    OptionList:focus > .option-list--option-highlighted {\n        background: $accent;\n    }\n\n    OptionList > .option-list--option-disabled {\n        color: $text-disabled;\n    }\n\n    OptionList > .option-list--option-highlighted-disabled {\n        color: $text-disabled;\n        background: $accent 30%;\n    }\n\n    OptionList:focus > .option-list--option-highlighted-disabled {\n        background: $accent 40%;\n    }\n\n    OptionList > .option-list--option-hover {\n        background: $boost;\n    }\n\n    OptionList > .option-list--option-hover-disabled {\n        color: $text-disabled;\n        background: $boost;\n    }\n\n    OptionList > .option-list--option-hover-highlighted {\n        background: $accent 60%;\n        color: $text;\n        text-style: bold;\n    }\n\n    OptionList:focus > .option-list--option-hover-highlighted {\n        background: $accent;\n        color: $text;\n        text-style: bold;\n    }\n\n    OptionList > .option-list--option-hover-highlighted-disabled {\n        color: $text-disabled;\n        background: $accent 60%;\n    }\n    "

The default styling for an OptionList.

highlighted `class-attribute` `instance-attribute` ¶

highlighted: reactive[int | None] = None

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

option_count `property` ¶

option_count: int

The count of options.

OptionHighlighted `class` ¶

Bases: OptionMessage

Message sent when an option is highlighted.

Can be handled using on_option_list_option_highlighted in a subclass of OptionList or in a parent node in the DOM.

OptionMessage `class` ¶

def __init__(self, option_list, index):

Bases: Message

Base class for all option messages.

Parameters

Name	Type	Description	Default
`option_list`	`OptionList`	The option list that owns the option.	required
`index`	`int`	The index of the option that the message relates to.	required

control `property` ¶

control: OptionList

The option list that sent the message.

This is an alias for OptionMessage.option_list and is used by the on decorator.

option `instance-attribute` ¶

option: Option = option_list.get_option_at_index(index)

The highlighted option.

option_id `instance-attribute` ¶

option_id: str | None = self.option.id

The ID of the option that the message relates to.

option_index `instance-attribute` ¶

option_index: int = index

The index of the option that the message relates to.

option_list `instance-attribute` ¶

option_list: OptionList = option_list

The option list that sent the message.

OptionSelected `class` ¶

Bases: OptionMessage

Message sent when an option is selected.

Can be handled using on_option_list_option_selected in a subclass of OptionList or in a parent node in the DOM.

action_cursor_down `method` ¶

def action_cursor_down(self):

Move the highlight down by one option.

action_cursor_up `method` ¶

def action_cursor_up(self):

Move the highlight up by one option.

action_first `method` ¶

def action_first(self):

Move the highlight to the first option.

action_last `method` ¶

def action_last(self):

Move the highlight to the last option.

action_page_down `method` ¶

def action_page_down(self):

Move the highlight down one page.

action_page_up `method` ¶

def action_page_up(self):

Move the highlight up one page.

action_select `method` ¶

def action_select(self):

Select the currently-highlighted option.

If no option is selected, then nothing happens. If an option is selected, a OptionList.OptionSelected message will be posted.

add_option `method` ¶

def add_option(self, item=None):

Add a new option to the end of the option list.

Parameters

Name	Type	Description	Default
`item`	`NewOptionListContent`	The new item to add.	`None`

Returns

Type	Description
`Self`	The `OptionList` instance.

Raises

Type	Description
`DuplicateID`	If there is an attempt to use a duplicate ID.

add_options `method` ¶

def add_options(self, items):

Add new options to the end of the option list.

Parameters

Name	Type	Description	Default
`items`	`Iterable[NewOptionListContent]`	The new items to add.	required

Returns

Type	Description
`Self`	The `OptionList` instance.

Raises

Type	Description
`DuplicateID`	If there is an attempt to use a duplicate ID.

clear_options `method` ¶

def clear_options(self):

Clear the content of the option list.

Returns

Type	Description
`Self`	The `OptionList` instance.

disable_option `method` ¶

def disable_option(self, option_id):

Disable the option with the given ID.

Parameters

Name	Type	Description	Default
`option_id`	`str`	The ID of the option to disable.	required

Returns

Type	Description
`Self`	The `OptionList` instance.

Raises

Type	Description
`OptionDoesNotExist`	If no option has the given ID.

disable_option_at_index `method` ¶

def disable_option_at_index(self, index):

Disable the option at the given index.

Returns

Type	Description
`Self`	The `OptionList` instance.

Raises

Type	Description
`OptionDoesNotExist`	If there is no option with the given index.

enable_option `method` ¶

def enable_option(self, option_id):

Enable the option with the given ID.

Parameters

Name	Type	Description	Default
`option_id`	`str`	The ID of the option to enable.	required

Returns

Type	Description
`Self`	The `OptionList` instance.

Raises

Type	Description
`OptionDoesNotExist`	If no option has the given ID.

enable_option_at_index `method` ¶

def enable_option_at_index(self, index):

Enable the option at the given index.

Returns

Type	Description
`Self`	The `OptionList` instance.

Raises

Type	Description
`OptionDoesNotExist`	If there is no option with the given index.

get_option `method` ¶

def get_option(self, option_id):

Get the option with the given ID.

Parameters

Name	Type	Description	Default
`option_id`	`str`	The ID of the option to get.	required

Returns

Type	Description
`Option`	The option at with the ID.

Raises

Type	Description
`OptionDoesNotExist`	If no option has the given ID.

get_option_at_index `method` ¶

def get_option_at_index(self, index):

Get the option at the given index.

Parameters

Name	Type	Description	Default
`index`	`int`	The index of the option to get.	required

Returns

Type	Description
`Option`	The option at that index.

Raises

Type	Description
`OptionDoesNotExist`	If there is no option with the index.

remove_option `method` ¶

def remove_option(self, option_id):

Remove the option with the given ID.

Parameters

Name	Type	Description	Default
`option_id`	`str`	The ID of the option to remove.	required

Returns

Type	Description
`Self`	The `OptionList` instance.

Raises

Type	Description
`OptionDoesNotExist`	If no option has the given ID.

remove_option_at_index `method` ¶

def remove_option_at_index(self, index):

Remove the option at the given index.

Parameters

Name	Type	Description	Default
`index`	`int`	The index of the option to remove.	required

Returns

Type	Description
`Self`	The `OptionList` instance.

Raises

Type	Description
`OptionDoesNotExist`	If there is no option with the given index.

render_line `method` ¶

def render_line(self, y):

Render a single line in the option list.

Parameters

Name	Type	Description	Default
`y`	`int`	The Y offset of the line to render.	required

Returns

Type	Description
`Strip`	A `Strip` instance for the caller to render.

scroll_to_highlight `method` ¶

def scroll_to_highlight(self, top=False):

Ensure that the highlighted option is in view.

Parameters

Name	Type	Description	Default
`top`	`bool`	Scroll highlight to top of the list.	`False`

validate_highlighted `method` ¶

def validate_highlighted(self, highlighted):

Validate the highlighted property value on access.

watch_highlighted `method` ¶

def watch_highlighted(self, highlighted):

React to the highlighted option having changed.

watch_show_vertical_scrollbar `method` ¶

def watch_show_vertical_scrollbar(self):

Handle the vertical scrollbar visibility status changing.

show_vertical_scrollbar is watched because it has an impact on the available width in which to render the renderables that make up the options in the list. If a vertical scrollbar appears or disappears we need to recalculate all the lines that make up the list.

DuplicateID `class` ¶

Bases: Exception

Exception raised if a duplicate ID is used.

Option `class` ¶

def __init__(self, prompt, id=None, disabled=False):

Class that holds the details of an individual option.

Parameters

Name	Type	Description	Default
`prompt`	`RenderableType`	The prompt for the option.	required
`id`	`str \| None`	The optional ID for the option.	`None`
`disabled`	`bool`	The initial enabled/disabled state. Enabled by default.	`False`

id `property` ¶

id: str | None

The optional ID for the option.

prompt `property` ¶

prompt: RenderableType

The prompt for the option.

OptionDoesNotExist `class` ¶

Bases: Exception

Exception raised when a request has been made for an option that doesn't exist.

Separator `class` ¶

Class used to add a separator to an OptionList.

OptionList¶

Examples¶

Options as simple strings¶

Options as Option instances¶

Options as Rich renderables¶

Reactive Attributes¶

Messages¶

Bindings¶

Component Classes¶

textual.widgets.OptionList class ¶

Parameters

BINDINGS class-attribute ¶

COMPONENT_CLASSES class-attribute ¶

DEFAULT_CSS class-attribute instance-attribute ¶

highlighted class-attribute instance-attribute ¶

option_count property ¶

OptionHighlighted class ¶

OptionMessage class ¶

Parameters

control property ¶

option instance-attribute ¶

option_id instance-attribute ¶

option_index instance-attribute ¶

option_list instance-attribute ¶

OptionSelected class ¶

action_cursor_down method ¶

action_cursor_up method ¶

action_first method ¶

action_last method ¶

action_page_down method ¶

action_page_up method ¶

action_select method ¶

add_option method ¶

Parameters

Returns

Raises

add_options method ¶

Parameters

Returns

Raises

clear_options method ¶

Returns

disable_option method ¶

Parameters

Returns

Raises

disable_option_at_index method ¶

Returns

Raises

enable_option method ¶

Parameters

Returns

Raises

enable_option_at_index method ¶

Returns

Raises

get_option method ¶

Parameters

Returns

Raises

get_option_at_index method ¶

Parameters

Returns

Raises

remove_option method ¶

Parameters

Returns

Raises

remove_option_at_index method ¶

Parameters

Returns

Raises

render_line method ¶

Parameters

Returns

scroll_to_highlight method ¶

Parameters

validate_highlighted method ¶

watch_highlighted method ¶

watch_show_vertical_scrollbar method ¶

Options as `Option` instances¶

textual.widgets.OptionList `class` ¶

BINDINGS `class-attribute` ¶

COMPONENT_CLASSES `class-attribute` ¶

DEFAULT_CSS `class-attribute` `instance-attribute` ¶

highlighted `class-attribute` `instance-attribute` ¶

option_count `property` ¶

OptionHighlighted `class` ¶

OptionMessage `class` ¶

control `property` ¶

option `instance-attribute` ¶

option_id `instance-attribute` ¶

option_index `instance-attribute` ¶

option_list `instance-attribute` ¶

OptionSelected `class` ¶

action_cursor_down `method` ¶

action_cursor_up `method` ¶

action_first `method` ¶

action_last `method` ¶

action_page_down `method` ¶

action_page_up `method` ¶

action_select `method` ¶

add_option `method` ¶

add_options `method` ¶

clear_options `method` ¶

disable_option `method` ¶

disable_option_at_index `method` ¶

enable_option `method` ¶

enable_option_at_index `method` ¶

get_option `method` ¶

get_option_at_index `method` ¶

remove_option `method` ¶

remove_option_at_index `method` ¶

render_line `method` ¶

scroll_to_highlight `method` ¶

validate_highlighted `method` ¶

watch_highlighted `method` ¶

watch_show_vertical_scrollbar `method` ¶

DuplicateID `class` ¶

Option `class` ¶

id `property` ¶

prompt `property` ¶

OptionDoesNotExist `class` ¶

Separator `class` ¶