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.

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[Optional[int]](
    0, always_update=True, init=False
)

The index of the currently highlighted item.

Highlighted ¶

Highlighted(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

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

The highlighted item, if there is one highlighted.

list_view `instance-attribute` ¶

list_view = list_view

The view that contains the item highlighted.

Selected ¶

Selected(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

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

The selected item.

list_view `instance-attribute` ¶

list_view = list_view

The view that contains the item selected.

action_cursor_down ¶

action_cursor_down()

Highlight the next item in the list.

action_cursor_up ¶

action_cursor_up()

Highlight the previous item in the list.

action_select_cursor ¶

action_select_cursor()

Select the current item in the list.

append ¶

append(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 ¶

clear()

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 ¶

extend(items)

Append multiple new ListItems to the end of the ListView.

Parameters:

Name	Type	Description	Default
`items` ¶	`Iterable[ListItem]`	The ListItems 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 items.

insert ¶

insert(index, items)

Insert new ListItem(s) to specified index.

Parameters:

Name	Type	Description	Default
`index` ¶	`int`	index to insert new ListItem.	required
`items` ¶	`Iterable[ListItem]`	The ListItems to insert.	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.

pop ¶

pop(index=None)

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

Parameters:

Name	Type	Description	Default
`index` ¶	`Optional[int]`	index of ListItem to remove from ListView	`None`

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 ¶

remove_items(indices)

Remove ListItems from ListView by indices

Parameters:

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

Returns:

Type	Description
`AwaitRemove`	An awaitable object that waits for the direct children to be removed.

validate_index ¶

validate_index(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 ¶

watch_index(old_index, new_index)

Updates the highlighting when the index changes.

ListView¶

Example¶

Reactive Attributes¶

Messages¶

Bindings¶

Component Classes¶

*children ¶

initial_index ¶

name ¶

id ¶

classes ¶

disabled ¶

BINDINGS class-attribute ¶

highlighted_child property ¶

index class-attribute instance-attribute ¶

Highlighted ¶

ALLOW_SELECTOR_MATCH class-attribute instance-attribute ¶

control property ¶

item instance-attribute ¶

list_view instance-attribute ¶

Selected ¶

ALLOW_SELECTOR_MATCH class-attribute instance-attribute ¶

control property ¶

item instance-attribute ¶

list_view instance-attribute ¶

action_cursor_down ¶

action_cursor_up ¶

action_select_cursor ¶

append ¶

item ¶

clear ¶

extend ¶

items ¶

insert ¶

index ¶

items ¶

pop ¶

index ¶

remove_items ¶

indices ¶

validate_index ¶

index ¶

watch_index ¶

`*children` ¶

`initial_index` ¶

`name` ¶

`id` ¶

`classes` ¶

`disabled` ¶

BINDINGS `class-attribute` ¶

highlighted_child `property` ¶

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

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

control `property` ¶

item `instance-attribute` ¶

list_view `instance-attribute` ¶

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

control `property` ¶

item `instance-attribute` ¶

list_view `instance-attribute` ¶

`item` ¶

`items` ¶

`index` ¶

`items` ¶

`index` ¶

`indices` ¶

`index` ¶