textual/docs/widgets/selection_list.md

SelectionList

!!! tip "Added in version 0.??.0"

A widget for showing a vertical list check boxes.

• Focusable
• Container

Examples

A selection list is designed to be built up of single-line prompts (which can be Rich renderables) and an associated unique value.

Selections as tuples

A selection list can be built with tuples, either of two or three values in length. Each tuple must contain a prompt and a value, and it can also optionally contain a flag for the initial selected state of the option.

=== "Output"

```{.textual path="docs/examples/widgets/selection_list_tuples.py"}
```

=== "selection_list_tuples.py"

~~~python
--8<-- "docs/examples/widgets/selection_list_tuples.py"
~~~

=== "selection_list.css"

~~~python
--8<-- "docs/examples/widgets/selection_list.css"
~~~

Selections as Selection objects

Alternatively, selections can be passed in as [Selection][textual.widgets.selection_list.Selection]s:

=== "Output"

```{.textual path="docs/examples/widgets/selection_list_selections.py"}
```

=== "selection_list_selections.py"

~~~python
--8<-- "docs/examples/widgets/selection_list_selections.py"
~~~

=== "selection_list.css"

~~~python
--8<-- "docs/examples/widgets/selection_list.css"
~~~

Reactive Attributes

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

Messages

The following messages will be posted as the user interacts with the list:

• [SelectionList.SelectionHighlighted][textual.widgets.SelectionList.SelectionHighlighted]
• [SelectionList.SelectionToggled][textual.widgets.SelectionList.SelectionToggled]

The following message will be posted if the content of [selected][textual.widgets.SelectionList.selected] changes, either by user interaction or by API calls:

• [SelectionList.SelectedChanged][textual.widgets.SelectionList.SelectedChanged]

Bindings

The selection list widget defines the following bindings:

::: textual.widgets.SelectionList.BINDINGS options: show_root_heading: false show_root_toc_entry: false

It inherits from [OptionList][textual.widgets.OptionList] and so also inherits the following bindings:

::: textual.widgets.OptionList.BINDINGS options: show_root_heading: false show_root_toc_entry: false

Component Classes

The selection list provides the following component classes:

::: textual.widgets.SelectionList.COMPONENT_CLASSES options: show_root_heading: false show_root_toc_entry: false

It inherits from [OptionList][textual.widgets.OptionList] and so also makes use of the following component classes:

::: textual.widgets.OptionList.COMPONENT_CLASSES options: show_root_heading: false show_root_toc_entry: false

::: textual.widgets.SelectionList options: heading_level: 2

::: textual.widgets.selection_list options: heading_level: 2