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.

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

insert `method` ¶

def insert(self, index, items):

Insert new ListItem(s) to specified index.

Parameters

Parameter	Default	Description
`index` `int`	required	index to insert new ListItem.
`items` `Iterable[ListItem]`	required	The ListItems to insert.

Returns

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

pop `method` ¶

def pop(self, index=None):

Remove last ListItem from ListView or Remove ListItem from ListView by index

Parameters

Parameter	Default	Description
`index` `Optional[int]`	`None`	index of ListItem to remove from ListView

Returns

Type	Description
`AwaitRemove`	An awaitable that yields control to the event loop until the DOM has been updated to reflect item being removed.

remove_items `method` ¶

def remove_items(self, indices):

Remove ListItems from ListView by indices

Parameters

Parameter	Default	Description
`indices` `Iterable[int]`	required	index(s) of ListItems to remove from ListView

Returns

Type	Description
`AwaitRemove`	An awaitable object that waits for the direct children to be 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

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.

ListView¶

Example¶

Reactive Attributes¶

Messages¶

Bindings¶

Component Classes¶

textual.widgets.ListView class ¶

Attributes

Parameters

BINDINGS class-attribute ¶

highlighted_child property ¶

index instance-attribute class-attribute ¶

Highlighted class ¶

ALLOW_SELECTOR_MATCH instance-attribute class-attribute ¶

control property ¶

item instance-attribute ¶

list_view instance-attribute ¶

Selected class ¶

ALLOW_SELECTOR_MATCH instance-attribute class-attribute ¶

control property ¶

item instance-attribute ¶

list_view instance-attribute ¶

action_cursor_down method ¶

action_cursor_up method ¶

action_select_cursor method ¶

append method ¶

Parameters

Returns

clear method ¶

Returns

extend method ¶

Parameters

Returns

insert method ¶

Parameters

Returns

pop method ¶

Parameters

Returns

remove_items method ¶

Parameters

Returns

validate_index method ¶

Parameters

Returns

watch_index method ¶

textual.widgets.ListView `class` ¶

BINDINGS `class-attribute` ¶

highlighted_child `property` ¶

index `instance-attribute` `class-attribute` ¶

Highlighted `class` ¶

ALLOW_SELECTOR_MATCH `instance-attribute` `class-attribute` ¶

control `property` ¶

item `instance-attribute` ¶

list_view `instance-attribute` ¶

Selected `class` ¶

ALLOW_SELECTOR_MATCH `instance-attribute` `class-attribute` ¶

control `property` ¶

item `instance-attribute` ¶

list_view `instance-attribute` ¶

action_cursor_down `method` ¶

action_cursor_up `method` ¶

action_select_cursor `method` ¶

append `method` ¶

clear `method` ¶

extend `method` ¶

insert `method` ¶

pop `method` ¶

remove_items `method` ¶

validate_index `method` ¶

watch_index `method` ¶