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.

---

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 = [
    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

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

index class-attribute instance-attribute

index = reactive[