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.

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 Textual markup if `True`, or plain text if `False`.	`True`

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.

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

highlighted = reactive(None)

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

option_count `property` ¶

option_count

The number of options.

options `property` ¶

options

Sequence of options in the OptionList.

This is read-only

OptionHighlighted ¶

OptionHighlighted(option_list, option, 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.

OptionMessage ¶

OptionMessage(option_list, option, 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 = option

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, option, 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.

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 one page.

action_page_up ¶

action_page_up()

Move the highlight up one page.

action_select ¶

action_select()

Select the currently highlighted option.

If an option is selected then a OptionList.OptionSelected will be posted.

add_option ¶

add_option(option=None)

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

Parameters:

Name	Type	Description	Default
`option` ¶	`Option \| VisualType \| None`	New option to add, or `None` for a separator.	`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(new_options)

Add new options.

Parameters:

Name	Type	Description	Default
`new_options` ¶	`Iterable[OptionListContent]`	Content of new options.	required

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 (offset in self.options) 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` ¶	`VisualType`	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` ¶	`VisualType`	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)

Scroll to the highlighted option.

Parameters:

Name	Type	Description	Default
`top` ¶	`bool`	Ensure highlighted option is at the top of the widget.	`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: OptionListError

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

Option ¶

Option(prompt, id=None, disabled=False)

This class holds details of options in the list.

Parameters:

Name	Type	Description	Default
`prompt` ¶	`VisualType`	The prompt (text displayed) for the option.	required
`id` ¶	`str \| None`	An option ID for the option.	`None`
`disabled` ¶	`bool`	Disable the option (will be shown grayed out, and will not be selectable).	`False`

id `property` ¶

id

Optional ID for the option.

prompt `property` ¶

prompt

The original prompt.

OptionDoesNotExist ¶

Bases: OptionListError

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

OptionList¶

Examples¶

Options as simple strings¶

Options as Option instances¶

Options as Rich renderables¶

Reactive Attributes¶

Messages¶

Bindings¶

Component Classes¶

*content ¶

name ¶

id ¶

classes ¶

disabled ¶

markup ¶

BINDINGS class-attribute ¶

COMPONENT_CLASSES class-attribute ¶

highlighted class-attribute instance-attribute ¶

option_count property ¶

options property ¶

OptionHighlighted ¶

OptionMessage ¶

option_list ¶

index ¶

control property ¶

option instance-attribute ¶

option_id instance-attribute ¶

option_index instance-attribute ¶

option_list instance-attribute ¶

OptionSelected ¶

action_cursor_down ¶

action_cursor_up ¶

action_first ¶

action_last ¶

action_page_down ¶

action_page_up ¶

action_select ¶

add_option ¶

option ¶

add_options ¶

new_options ¶

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 ¶

OptionDoesNotExist ¶

Options as `Option` instances¶

`*content` ¶

`name` ¶

`id` ¶

`classes` ¶

`disabled` ¶

`markup` ¶

BINDINGS `class-attribute` ¶

COMPONENT_CLASSES `class-attribute` ¶

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

option_count `property` ¶

options `property` ¶

`option_list` ¶

`index` ¶

control `property` ¶

option `instance-attribute` ¶

option_id `instance-attribute` ¶

option_index `instance-attribute` ¶

option_list `instance-attribute` ¶

`option` ¶

`new_options` ¶

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