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: list[BindingType] = [
    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: set[str] = {
    "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: TreeNode[TreeDataType] | None

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: int

The index of the last line.

root instance-attribute

root = self._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: Tree[EventTreeDataType]

The tree that sent the message.

node instance-attribute

node: TreeNode[EventTreeDataType] = 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: Tree[EventTreeDataType]

The tree that sent the message.

node instance-attribute

node: TreeNode[EventTreeDataType] = node

The node that was expanded.

NodeHighlighted

NodeHighlighted(node)

Bases: Generic[EventTreeDataType], Message

Event sent when a node is highlighted.

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

control property

control: Tree[EventTreeDataType]

The tree that sent the message.

node instance-attribute

node: TreeNode[EventTreeDataType] = node

The node that was highlighted.

NodeSelected

NodeSelected(node)

Bases: Generic[EventTreeDataType], Message

Event sent when a node is selected.

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

control property

control: Tree[EventTreeDataType]

The tree that sent the message.

node instance-attribute

node: TreeNode[EventTreeDataType] = node

The node that was selected.

action_cursor_down

action_cursor_down()

Move the cursor down one node.

action_cursor_next_sibling

action_cursor_next_sibling()

Move the cursor to the next sibling, or to the paren't sibling if there are no more siblings.

action_cursor_parent

action_cursor_parent()

Move the cursor to the parent node.

action_cursor_parent_next_sibling

action_cursor_parent_next_sibling()

Move the cursor to the parent's next sibling.

action_cursor_previous_sibling

action_cursor_previous_sibling()

Move the cursor to previous sibling, or to the parent if there are no more siblings.

action_cursor_up

action_cursor_up()

Move the cursor up one node.

action_page_down

action_page_down()

Move the cursor down a page's-worth of nodes.

action_page_up

action_page_up()

Move the cursor up a page's-worth of nodes.

action_scroll_end

action_scroll_end()

Move the cursor to the bottom of the tree.

Note

Here bottom means vertically, not branch depth.

action_scroll_home

action_scroll_home()

Move the cursor to the top of the tree.

action_select_cursor

action_select_cursor()

Cause a select event for the target node.

Note

If auto_expand is True use of this action on a non-leaf node will cause both an expand/collapse event to occur, as well as a selected event.

action_toggle_expand_all

action_toggle_expand_all()

Expand or collapse all siblings.

If all the siblings are collapsed then they will be expanded. Otherwise they will all be collapsed.

action_toggle_node

action_toggle_node()

Toggle the expanded state of the target node.

add_json

add_json(json_data, node=None)

Adds JSON data to a node.

Parameters:

Name	Type	Description	Default
json_data	object	An object decoded from JSON.	required
node	TreeNode | None	Node to add data to.	None

clear

clear()

Clear all nodes under root.

Returns:

Type	Description
Self	The Tree instance.

get_label_width

get_label_width(node)

Get the width of the nodes label.

The default behavior is to call render_label and return the cell length. This method may be overridden in a sub-class if it can be done more efficiently.

Parameters:

Name	Type	Description	Default
node	TreeNode[TreeDataType]	A node.	required

Returns:

Type	Description
int	Width in cells.

get_node_at_line

get_node_at_line(line_no)

Get the node for a given line.

Parameters:

Name	Type	Description	Default
line_no	int	A line number.	required

Returns:

Type	Description
TreeNode[TreeDataType] | None	A tree node, or None if there is no node at that line.

get_node_by_id

get_node_by_id(node_id)

Get a tree node by its ID.

Parameters:

Name	Type	Description	Default
node_id	NodeID	The ID of the node to get.	required

Returns:

Type	Description
TreeNode[TreeDataType]	The node associated with that ID.

Raises:

Type	Description
UnknownNodeID	Raised if the TreeNode ID is unknown.

move_cursor

move_cursor(node, animate=False)

Move the cursor to the given node, or reset cursor.

Parameters:

Name	Type	Description	Default
node	TreeNode[TreeDataType] | None	A tree node, or None to reset cursor.	required
animate	bool	Enable animation	False

move_cursor_to_line

move_cursor_to_line(line, animate=False)

Move the cursor to the given line.

Parameters:

Name	Type	Description	Default
line	int	The line number (negative indexes are offsets from the last line).	required
animate		Enable scrolling animation.	False

Raises:

Type	Description
IndexError	If the line doesn't exist.

process_label

process_label(label)

Process a str or Text value into a label.

May be overridden in a subclass to change how labels are rendered.

Parameters:

Name	Type	Description	Default
label	TextType	Label.	required

Returns:

Type	Description
Text	A Rich Text object.

render_label

render_label(node, base_style, style)

Render a label for the given node. Override this to modify how labels are rendered.

Parameters:

Name	Type	Description	Default
node	TreeNode[TreeDataType]	A tree node.	required
base_style	Style	The base style of the widget.	required
style	Style	The additional style for the label.	required

Returns:

Type	Description
Text	A Rich Text object containing the label.

reset

reset(label, data=None)

Clear the tree and reset the root node.

Parameters:

Name	Type	Description	Default
label	TextType	The label for the root node.	required
data	TreeDataType | None	Optional data for the root node.	None

Returns:

Type	Description
Self	The Tree instance.

scroll_to_line

scroll_to_line(line, animate=True)

Scroll to the given line.

Parameters:

Name	Type	Description	Default
line	int	A line number.	required
animate	bool	Enable animation.	True

scroll_to_node

scroll_to_node(node, animate=True)

Scroll to the given node.

Parameters:

Name	Type	Description	Default
node	TreeNode[TreeDataType]	Node to scroll into view.	required
animate	bool	Animate scrolling.	True

select_node

select_node(node)

Move the cursor to the given node and select it, or reset cursor.

Parameters:

Name	Type	Description	Default
node	TreeNode[TreeDataType] | None	A tree node to move the cursor to and select, or None to reset cursor.	required

unselect

unselect()

Hide and reset the cursor.

validate_cursor_line

validate_cursor_line(value)

Prevent cursor line from going outside of range.

Parameters:

Name	Type	Description	Default
value	int	The value to test.	required

Return

A valid version of the given value.

validate_guide_depth

validate_guide_depth(value)

Restrict guide depth to reasonable range.

Parameters:

Name	Type	Description	Default
value	int	The value to test.	required

Return

A valid version of the given value.

---

Make non-widget Tree support classes available.

EventTreeDataType module-attribute

EventTreeDataType = TypeVar('EventTreeDataType')

The type of the data for a given instance of a Tree.

Similar to TreeDataType but used for Tree messages.

NodeID module-attribute

NodeID = NewType('NodeID', int)

The type of an ID applied to a TreeNode.

TreeDataType module-attribute

TreeDataType = TypeVar('TreeDataType')

The type of the data for a given instance of a Tree.

AddNodeError

Bases: Exception

Exception raised when there is an error with a request to add a node.

RemoveRootError

Bases: Exception

Exception raised when trying to remove the root of a TreeNode.

TreeNode

TreeNode(
    tree,
    parent,
    id,
    label,
    data=None,
    *,
    expanded=True,
    allow_expand=True
)

Bases: Generic[TreeDataType]

An object that represents a "node" in a tree control.

Parameters:

Name	Type	Description	Default
tree	Tree[TreeDataType]	The tree that the node is being attached to.	required
parent	TreeNode[TreeDataType] | None	The parent node that this node is being attached to.	required
id	NodeID	The ID of the node.	required
label	Text	The label for the node.	required
data	TreeDataType | None	Optional data to associate with the node.	None
expanded	bool	Should the node be attached in an expanded state?	True
allow_expand	bool	Should the node allow being expanded by the user?	True

allow_expand property writable

allow_expand: bool

Is this node allowed to expand?

children property

children: TreeNodes[TreeDataType]

The child nodes of a TreeNode.

data instance-attribute

data = data

Optional data associated with the tree node.

id property

id: NodeID

The ID of the node.

is_collapsed property

is_collapsed: bool

Is the node collapsed?

is_expanded property

is_expanded: bool

Is the node expanded?

is_last property

is_last: bool

Is this the last child node of its parent?

is_root property

is_root: bool

Is this node the root of the tree?

label property writable

label: TextType

The label for the node.

line property

line: int

The line number for this node, or -1 if it is not displayed.

next_sibling property

next_sibling: TreeNode[TreeDataType] | None

The next sibling below the node.

parent property

parent: TreeNode[TreeDataType] | None

The parent of the node.

previous_sibling property

previous_sibling: TreeNode[TreeDataType] | None

The previous sibling below the node.

siblings property

siblings: TreeNodes[TreeDataType]

The siblings of this node (includes self).

tree property

tree: Tree[TreeDataType]

The tree that this node is attached to.

add

add(
    label,
    data=None,
    *,
    before=None,
    after=None,
    expand=False,
    allow_expand=True
)

Add a node to the sub-tree.

Parameters:

Name	Type	Description	Default
label	TextType	The new node's label.	required
data	TreeDataType | None	Data associated with the new node.	None
before	int | TreeNode[TreeDataType] | None	Optional index or TreeNode to add the node before.	None
after	int | TreeNode[TreeDataType] | None	Optional index or TreeNode to add the node after.	None
expand	bool	Node should be expanded.	False
allow_expand	bool	Allow user to expand the node via keyboard or mouse.	True

Returns:

Type	Description
TreeNode[TreeDataType]	A new Tree node

Raises:

Type	Description
AddNodeError	If there is a problem with the addition request.

Note

Only one of before or after can be provided. If both are provided a AddNodeError will be raised.

add_leaf

add_leaf(label, data=None, *, before=None, after=None)

Add a 'leaf' node (a node that can not expand).

Parameters:

Name	Type	Description	Default
label	TextType	Label for the node.	required
data	TreeDataType | None	Optional data.	None
before	int | TreeNode[TreeDataType] | None	Optional index or TreeNode to add the node before.	None
after	int | TreeNode[TreeDataType] | None	Optional index or TreeNode to add the node after.	None

Returns:

Type	Description
TreeNode[TreeDataType]	New node.

Raises:

Type	Description
AddNodeError	If there is a problem with the addition request.

Note

Only one of before or after can be provided. If both are provided a AddNodeError will be raised.

collapse

collapse()

Collapse the node (hide its children).

Returns:

Type	Description
Self	The TreeNode instance.

collapse_all

collapse_all()

Collapse the node (hide its children) and all those below it.

Returns:

Type	Description
Self	The TreeNode instance.

expand

expand()

Expand the node (show its children).

Returns:

Type	Description
Self	The TreeNode instance.

expand_all

expand_all()

Expand the node (show its children) and all those below it.

Returns:

Type	Description
Self	The TreeNode instance.

refresh

refresh()

Initiate a refresh (repaint) of this node.

remove

remove()

Remove this node from the tree.

Raises:

Type	Description
RemoveRootError	If there is an attempt to remove the root.

remove_children

remove_children()

Remove any child nodes of this node.

set_label

set_label(label)

Set a new label for the node.

Parameters:

Name	Type	Description	Default
label	TextType	A str or Text object with the new label.	required

toggle

toggle()

Toggle the node's expanded state.

Returns:

Type	Description
Self	The TreeNode instance.

toggle_all

toggle_all()

Toggle the node's expanded state and make all those below it match.

Returns:

Type	Description
Self	The TreeNode instance.

UnknownNodeID

Bases: Exception

Exception raised when referring to an unknown TreeNode ID.