Skip to content

List view

ListView

Bases: Vertical

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.

highlighted_child: ListItem | None property

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

Highlighted

Bases: Message

Emitted when the highlighted item changes. Highlighted item is controlled using up/down keys.

Attributes:

Name Type Description
item ListItem | None

The highlighted item, if there is one highlighted.

Selected

Bases: Message

Emitted when a list item is selected, e.g. when you press the enter key on it

Attributes:

Name Type Description
item ListItem

The selected item.

__init__(*children, initial_index=0, name=None, id=None, classes=None)

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

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

on_mount()

Ensure the ListView is fully-settled after mounting.

validate_index(index)

Clamp the index to the valid range, or set to None if there's nothing to highlight.

watch_index(old_index, new_index)

Updates the highlighting when the index changes.