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.