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.

Outputlist_view.pylist_view.tcss

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

• ListView.Highlighted
• ListView.Selected

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.

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 instance-attribute class-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 instance-attribute class-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.