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, Separator


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"),
            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 {
    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.

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-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--option-hover-highlighted`	Target a highlighted option that has the mouse over it.
`option-list--separator`	Target the separators.

Bases: ScrollView

A vertical option list with bounce-bar highlighting.

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--option-hover-highlighted",
    "option-list--separator",
}

Class	Description
`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--option-hover-highlighted`	Target a highlighted option that has the mouse over it.
`option-list--separator`	Target the separators.

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

The count of options.

OptionHighlighted ¶

OptionHighlighted(option_list, index)

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.

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

OptionMessage ¶

OptionMessage(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

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 = get_option_at_index(index)

The highlighted option.

option_id `instance-attribute` ¶

option_id = id

The ID of the option that the message relates to.

option_index `instance-attribute` ¶

option_index = index

The index of the option that the message relates to.

option_list `instance-attribute` ¶

option_list = option_list

The option list that sent the message.

OptionSelected ¶

OptionSelected(option_list, index)

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.

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

action_cursor_down ¶

action_cursor_down()

Move the highlight down to the next enabled option.

action_cursor_up ¶

action_cursor_up()

Move the highlight up to the previous enabled option.

action_first ¶

action_first()

Move the highlight to the first enabled option.

action_last ¶

action_last()

Move the highlight to the last enabled option.

action_page_down ¶

action_page_down()

Move the highlight down roughly by one page.

action_page_up ¶

action_page_up()

Move the highlight up roughly by one page.

action_select ¶

action_select()

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 ¶

add_option(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 ¶

add_options(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.

Note

All options are checked for duplicate IDs before any option is added. A duplicate ID will cause none of the passed items to be added to the option list.

clear_options ¶

clear_options()

Clear the content of the option list.

Returns:

Type	Description
`Self`	The `OptionList` instance.

disable_option ¶

disable_option(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 ¶

disable_option_at_index(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 ¶

enable_option(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 ¶

enable_option_at_index(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 ¶

get_option(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 with the ID.

Raises:

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

get_option_at_index ¶

get_option_at_index(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 given index.

get_option_index ¶

get_option_index(option_id)

Get the index of the option with the given ID.

Parameters:

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

Returns:

Type	Description
`int`	The index of the item with the given ID.

Raises:

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

remove_option ¶

remove_option(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 ¶

remove_option_at_index(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.

replace_option_prompt ¶

replace_option_prompt(option_id, prompt)

Replace the prompt of the option with the given ID.

Parameters:

Name	Type	Description	Default
`option_id` ¶	`str`	The ID of the option to replace the prompt of.	required
`prompt` ¶	`RenderableType`	The new prompt for the option.	required

Returns:

Type	Description
`Self`	The `OptionList` instance.

Raises:

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

replace_option_prompt_at_index ¶

replace_option_prompt_at_index(index, prompt)

Replace the prompt of the option at the given index.

Parameters:

Name	Type	Description	Default
`index` ¶	`int`	The index of the option to replace the prompt of.	required
`prompt` ¶	`RenderableType`	The new prompt for the option.	required

Returns:

Type	Description
`Self`	The `OptionList` instance.

Raises:

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

scroll_to_highlight ¶

scroll_to_highlight(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 ¶

validate_highlighted(highlighted)

Validate the highlighted property value on access.

watch_highlighted ¶

watch_highlighted(highlighted)

React to the highlighted option having changed.

DuplicateID ¶

Bases: Exception

Raised if a duplicate ID is used when adding options to an option list.

Option ¶

Option(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

The optional ID for the option.

prompt `property` ¶

prompt

The prompt for the option.

set_prompt ¶

set_prompt(prompt)

Set the prompt for the option.

Parameters:

Name	Type	Description	Default
`prompt` ¶	`RenderableType`	The new prompt for the option.	required

OptionDoesNotExist ¶

Bases: Exception

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

Separator ¶

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¶

BINDINGS class-attribute ¶

COMPONENT_CLASSES class-attribute ¶

highlighted class-attribute instance-attribute ¶

option_count property ¶

OptionHighlighted ¶

option_list ¶

index ¶

OptionMessage ¶

option_list ¶

index ¶

control property ¶

option instance-attribute ¶

option_id instance-attribute ¶

option_index instance-attribute ¶

option_list instance-attribute ¶

OptionSelected ¶

option_list ¶

index ¶

action_cursor_down ¶

action_cursor_up ¶

action_first ¶

action_last ¶

action_page_down ¶

action_page_up ¶

action_select ¶

add_option ¶

item ¶

add_options ¶

items ¶

clear_options ¶

disable_option ¶

option_id ¶

disable_option_at_index ¶

enable_option ¶

option_id ¶

enable_option_at_index ¶

get_option ¶

option_id ¶

get_option_at_index ¶

index ¶

get_option_index ¶

option_id ¶

remove_option ¶

option_id ¶

remove_option_at_index ¶

index ¶

replace_option_prompt ¶

option_id ¶

prompt ¶

replace_option_prompt_at_index ¶

index ¶

prompt ¶

scroll_to_highlight ¶

top ¶

validate_highlighted ¶

watch_highlighted ¶

DuplicateID ¶

Option ¶

prompt ¶

id ¶

disabled ¶

id property ¶

prompt property ¶

set_prompt ¶

prompt ¶

OptionDoesNotExist ¶

Separator ¶

Options as `Option` instances¶

BINDINGS `class-attribute` ¶

COMPONENT_CLASSES `class-attribute` ¶

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

option_count `property` ¶

`option_list` ¶

`index` ¶

`option_list` ¶

`index` ¶

control `property` ¶

option `instance-attribute` ¶

option_id `instance-attribute` ¶

option_index `instance-attribute` ¶

option_list `instance-attribute` ¶

`option_list` ¶

`index` ¶

`item` ¶

`items` ¶

`option_id` ¶

`option_id` ¶

`option_id` ¶

`index` ¶

`option_id` ¶

`option_id` ¶

`index` ¶

`option_id` ¶

`prompt` ¶

`index` ¶

`prompt` ¶

`top` ¶

`prompt` ¶

`id` ¶

`disabled` ¶

id `property` ¶

prompt `property` ¶

`prompt` ¶