Skip to content

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:

OptionListApp OptionListApp ▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔ Aerilon Aquaria Canceron Caprica Gemenon Leonis Libran Picon Sagittaron Scorpia Tauron Virgon ▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁ ^p palette

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.

OptionListApp OptionListApp ▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔ Aerilon Aquaria ────────────────────────────────────────────────── Canceron Caprica ────────────────────────────────────────────────── Gemenon ────────────────────────────────────────────────── Leonis Libran ────────────────────────────────────────────────── Picon▁▁ ────────────────────────────────────────────────── Sagittaron Scorpia ▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁ ^p palette

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:

OptionListApp OptionListApp ▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔                  Data for Aerilon                  ┏━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┓ Patron God   Population   Capital City   ┡━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━┩▇▇ Demeter      1.2 Billion  Gaoth          └───────────────┴───────────────┴────────────────┘                  Data for Aquaria                  ┏━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┓ Patron God   Population   Capital City   ┡━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━┩ Hermes       75,000       None           └───────────────┴───────────────┴────────────────┘                 Data for Canceron                  ┏━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┓ Patron God   Population   Capital City   ▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁ ^p palette

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

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

RenderResult

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

RenderResult

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.