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 ListView, ListItem, Label, Footer


class ListViewExample(App):

    CSS_PATH = "list_view.css"

    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.

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
Name Type Description Default
*children ListItem

The ListItems to display in the list.

()
initial_index int | None

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

0
name str | None

The name of the widget.

None
id str | None

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

None
classes str | None

The CSS classes of the widget.

None
disabled bool

Whether the ListView is disabled or not.

False

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.

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
Name Type Description Default
item ListItem

The ListItem to append.

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

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
Name Type Description Default
index int | None

The index to clamp.

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