Tree

Added in version 0.6.0

A tree control widget.

• Focusable
• Container

Example

The example below creates a simple tree.

Outputtree.py

from textual.app import App, ComposeResult
from textual.widgets import Tree


class TreeApp(App):
    def compose(self) -> ComposeResult:
        tree: Tree[str] = Tree("Dune")
        tree.root.expand()
        characters = tree.root.add("Characters", expand=True)
        characters.add_leaf("Paul")
        characters.add_leaf("Jessica")
        characters.add_leaf("Chani")
        yield tree


if __name__ == "__main__":
    app = TreeApp()
    app.run()

Tree widgets have a "root" attribute which is an instance of a TreeNode. Call add() or add_leaf() to add new nodes underneath the root. Both these methods return a TreeNode for the child which you can use to add additional levels.

Reactive Attributes

Name	Type	Default	Description
show_root	bool	True	Show the root node.
show_guides	bool	True	Show guide lines between levels.
guide_depth	int	4	Amount of indentation between parent and child.

Messages

• Tree.NodeCollapsed
• Tree.NodeExpanded
• Tree.NodeHighlighted
• Tree.NodeSelected

Bindings

The tree widget defines the following bindings:

Key(s)	Description
enter	Select the current item.
space	Toggle the expand/collapsed state of the current item.
up	Move the cursor up.
down	Move the cursor down.

Component Classes

The tree widget provides the following component classes:

Class	Description
tree--cursor	Targets the cursor.
tree--guides	Targets the indentation guides.
tree--guides-hover	Targets the indentation guides under the cursor.
tree--guides-selected	Targets the indentation guides that are selected.
tree--highlight	Targets the highlighted items.
tree--highlight-line	Targets the lines under the cursor.
tree--label	Targets the (text) labels of the items.

---

Bases: Generic[TreeDataType], ScrollView

A widget for displaying and navigating data in a tree.

Parameters:

Name	Type	Description	Default
label	TextType	The label of the root node of the tree.	required
data	TreeDataType | None	The optional data to associate with the root node of the tree.	None
name	str | None	The name of the Tree.	None
id	str | None	The ID of the tree in the DOM.	None
classes	str | None	The CSS classes of the tree.	None
disabled	bool	Whether the tree is disabled or not.	False

BINDINGS class-attribute

BINDINGS = [
    Binding(
        "shift+left",
        "cursor_parent",
        "Cursor to parent",
        show=False,
    ),
    Binding(
        "shift+right",
        "cursor_parent_next_sibling",
        "Cursor to next ancestor",
        show=False,
    ),
    Binding(
        "shift+up",
        "cursor_previous_sibling",
        "Cursor to previous sibling",
        show=False,
    ),
    Binding(
        "shift+down",
        "cursor_next_sibling",
        "Cursor to next sibling",
        show=False,
    ),
    Binding("enter", "select_cursor", "Select", show=False),
    Binding("space", "toggle_node", "Toggle", show=False),
    Binding(
        "shift+space",
        "toggle_expand_all",
        "Expand or collapse all",
        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.
space	Toggle the expand/collapsed state of the current item.
up	Move the cursor up.
down	Move the cursor down.

COMPONENT_CLASSES class-attribute

COMPONENT_CLASSES = {
    "tree--cursor",
    "tree--guides",
    "tree--guides-hover",
    "tree--guides-selected",
    "tree--highlight",
    "tree--highlight-line",
    "tree--label",
}

Class	Description
tree--cursor	Targets the cursor.
tree--guides	Targets the indentation guides.
tree--guides-hover	Targets the indentation guides under the cursor.
tree--guides-selected	Targets the indentation guides that are selected.
tree--highlight	Targets the highlighted items.
tree--highlight-line	Targets the lines under the cursor.
tree--label	Targets the (text) labels of the items.

ICON_NODE class-attribute instance-attribute

ICON_NODE = '▶ '

Unicode 'icon' to use for an expandable node.

ICON_NODE_EXPANDED class-attribute instance-attribute

ICON_NODE_EXPANDED = '▼ '

Unicode 'icon' to use for an expanded node.

auto_expand class-attribute instance-attribute

auto_expand = var(True)

Auto expand tree nodes when they are selected.

center_scroll class-attribute instance-attribute

center_scroll = var(False)

Keep selected node in the center of the control, where possible.

cursor_line class-attribute instance-attribute

cursor_line = var(-1, always_update=True)

The line with the cursor, or -1 if no cursor.

cursor_node property

cursor_node

The currently selected node, or None if no selection.

guide_depth class-attribute instance-attribute

guide_depth = reactive(4, init=False)

The indent depth of tree nodes.

hover_line class-attribute instance-attribute

hover_line = var(-1)

The line number under the mouse pointer, or -1 if not under the mouse pointer.

last_line property

last_line

The index of the last line.

root instance-attribute

root = _add_node(None, text_label, data)

The root node of the tree.

show_guides class-attribute instance-attribute

show_guides = reactive(True)

Enable display of tree guide lines.

show_root class-attribute instance-attribute

show_root = reactive(True)

Show the root of the tree.

NodeCollapsed

NodeCollapsed(node)

Bases: Generic[EventTreeDataType], Message

Event sent when a node is collapsed.

Can be handled using on_tree_node_collapsed in a subclass of Tree or in a parent node in the DOM.

control property

control

The tree that sent the message.

node instance-attribute

node = node

The node that was collapsed.

NodeExpanded

NodeExpanded(node)

Bases: Generic[EventTreeDataType], Message

Event sent when a node is expanded.

Can be handled using on_tree_node_expanded in a subclass of Tree or in a parent node in the DOM.

control property

control

The tree that sent the message.

node instance-attribute

node = node

The node that was expanded.

NodeHighlighted