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

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

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

---

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.