Skip to content

ListView

Added in version 0.6.0

Displays a vertical list of ListItems which can be highlighted and selected. Supports keyboard navigation.

  • Focusable
  • Container

Example

The example below shows an app with a simple ListView.

ListViewExample One Two Three

from textual.app import App, ComposeResult
from textual.widgets import Footer, Label, ListItem, ListView


class ListViewExample(App):
    CSS_PATH = "list_view.tcss"

    def compose(self) -> ComposeResult:
        yield ListView(
            ListItem(Label("One")),
            ListItem(Label("Two")),
            ListItem(Label("Three")),
        )
        yield Footer()


if __name__ == "__main__":
    app = ListViewExample()
    app.run()
Screen {
    align: center middle;
}

ListView {
    width: 30;
    height: auto;
    margin: 2 2;
}

Label {
    padding: 1 2;
}

Reactive Attributes

Name Type Default Description
index int 0 The currently highlighted index.

Messages

Bindings

The list view widget defines the following bindings:

Key(s) Description
enter Select the current item.
up Move the cursor up.
down Move the cursor down.

Component Classes

This widget has no component classes.


textual.widgets.ListView class

def __init__(
    self,
    *children,
    initial_index=0,
    name=None,
    id=None,
    classes=None,
    disabled=False
):

Bases: VerticalScroll

A vertical list view widget.

Displays a vertical list of ListItems which can be highlighted and selected using the mouse or keyboard.

Attributes
Name Type Description
index

The index in the list that's currently highlighted.

Parameters
Parameter Default Description
*children
ListItem
()

The ListItems to display in the list.

initial_index
int | None
0

The index that should be highlighted when the list is first mounted.

name
str | None
None

The name of the widget.

id
str | None
None

The unique ID of the widget used in CSS/query selection.

classes
str | None
None

The CSS classes of the widget.

disabled
bool
False

Whether the ListView is disabled or not.

BINDINGS class-attribute

BINDINGS: list[BindingType] = [
    Binding("enter", "select_cursor", "Select", show=False),
    Binding("up", "cursor_up", "Cursor Up", show=False),
    Binding(
        "down", "cursor_down", "Cursor Down", show=False
    ),
]
Key(s) Description
enter Select the current item.
up Move the cursor up.
down Move the cursor down.

highlighted_child property

highlighted_child: ListItem | None

The currently highlighted ListItem, or None if nothing is highlighted.

index class-attribute instance-attribute

index = reactive[Optional[int]](
    0, always_update=True, init=False
)

The index of the currently highlighted item.

Highlighted class

def __init__(self, list_view, item):

Bases: Message

Posted when the highlighted item changes.

Highlighted item is controlled using up/down keys. Can be handled using on_list_view_highlighted in a subclass of ListView or in a parent widget in the DOM.

ALLOW_SELECTOR_MATCH class-attribute instance-attribute

ALLOW_SELECTOR_MATCH = {'item'}

Additional message attributes that can be used with the on decorator.

control property

control: ListView

The view that contains the item highlighted.

This is an alias for Highlighted.list_view and is used by the on decorator.

item instance-attribute

item: ListItem | None = item

The highlighted item, if there is one highlighted.

list_view instance-attribute

list_view: ListView = list_view

The view that contains the item highlighted.

Selected class

def __init__(self, list_view, item):

Bases: Message

Posted when a list item is selected, e.g. when you press the enter key on it.

Can be handled using on_list_view_selected in a subclass of ListView or in a parent widget in the DOM.

ALLOW_SELECTOR_MATCH class-attribute instance-attribute

ALLOW_SELECTOR_MATCH = {'item'}

Additional message attributes that can be used with the on decorator.

control property

control: ListView

The view that contains the item selected.

This is an alias for Selected.list_view and is used by the on decorator.

item instance-attribute

item: ListItem = item

The selected item.

list_view instance-attribute

list_view: ListView = list_view

The view that contains the item selected.

action_cursor_down method

def action_cursor_down(self):

Highlight the next item in the list.

action_cursor_up method

def action_cursor_up(self):

Highlight the previous item in the list.

action_select_cursor method

def action_select_cursor(self):

Select the current item in the list.

append method

def append(self, item):

Append a new ListItem to the end of the ListView.

Parameters
Parameter Default Description
item
ListItem
required

The ListItem to append.

Returns
Type Description
AwaitMount

An awaitable that yields control to the event loop until the DOM has been updated with the new child item.

clear method

def clear(self):

Clear all items from the ListView.

Returns
Type Description
AwaitRemove

An awaitable that yields control to the event loop until the DOM has been updated to reflect all children being removed.

extend method

def extend(self, items):

Append multiple new ListItems to the end of the ListView.

Parameters
Parameter Default Description
items
Iterable[ListItem]
required

The ListItems to append.

Returns
Type Description
AwaitMount

An awaitable that yields control to the event loop until the DOM has been updated with the new child items.

validate_index method

def validate_index(self, index):

Clamp the index to the valid range, or set to None if there's nothing to highlight.

Parameters
Parameter Default Description
index
int | None
required

The index to clamp.

Returns
Type Description
int | None

The clamped index.

watch_index method

def watch_index(self, old_index, new_index):

Updates the highlighting when the index changes.