DirectoryTree

A tree control to navigate the contents of your filesystem.

• Focusable
• Container

Example

The example below creates a simple tree to navigate the current working directory.

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


class DirectoryTreeApp(App):
    def compose(self) -> ComposeResult:
        yield DirectoryTree("./")


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

Filtering

There may be times where you want to filter what appears in the DirectoryTree. To do this inherit from DirectoryTree and implement your own version of the filter_paths method. It should take an iterable of Python Path objects, and return those that pass the filter. For example, if you wanted to take the above code an filter out all of the "hidden" files and directories:

Outputdirectory_tree_filtered.py

from pathlib import Path
from typing import Iterable

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


class FilteredDirectoryTree(DirectoryTree):
    def filter_paths(self, paths: Iterable[Path]) -> Iterable[Path]:
        return [path for path in paths if not path.name.startswith(".")]


class DirectoryTreeApp(App):
    def compose(self) -> ComposeResult:
        yield FilteredDirectoryTree("./")


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

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

• DirectoryTree.FileSelected

Bindings

The directory tree widget inherits the bindings from the tree widget.

Component Classes

The directory tree widget provides the following component classes:

Class	Description
directory-tree--extension	Target the extension of a file name.
directory-tree--file	Target files in the directory structure.
directory-tree--folder	Target folders in the directory structure.
directory-tree--hidden	Target hidden items in the directory structure.

See also the component classes for Tree.

See Also

• Tree code reference

---

Bases: Tree[DirEntry]

A Tree widget that presents files and directories.

Parameters:

Name	Type	Description	Default
path	str | Path	Path to directory.	required
name	str | None	The name of the widget, or None for no name.	None
id	str | None	The ID of the widget in the DOM, or None for no ID.	None
classes	str | None	A space-separated list of classes, or None for no classes.	None
disabled	bool	Whether the directory tree is disabled or not.	False

COMPONENT_CLASSES class-attribute

COMPONENT_CLASSES = {
    "directory-tree--extension",
    "directory-tree--file",
    "directory-tree--folder",
    "directory-tree--hidden",
}

Class	Description
directory-tree--extension	Target the extension of a file name.
directory-tree--file	Target files in the directory structure.
directory-tree--folder	Target folders in the directory structure.
directory-tree--hidden	Target hidden items in the directory structure.

See also the component classes for Tree.

ICON_FILE class-attribute instance-attribute

ICON_FILE = '📄 '

Unicode 'icon' to represent a file.

PATH class-attribute instance-attribute

PATH = Path

Callable that returns a fresh path object.

path class-attribute instance-attribute

path = path

The path that is the root of the directory tree.

Note

This can be set to either a str or a pathlib.Path object, but the value will always be a pathlib.Path object.

DirectorySelected

DirectorySelected(node, path)

Bases: Message

Posted when a directory is selected.

Can be handled using on_directory_tree_directory_selected in a subclass of DirectoryTree or in a parent widget in the DOM.

Parameters:

Name	Type	Description	Default
node	TreeNode[DirEntry]	The tree node for the directory that was selected.	required
path	Path	The path of the directory that was selected.	required

control property

control

The Tree that had a directory selected.

node instance-attribute

node = node

The tree node of the directory that was selected.

path instance-attribute

path = path

The path of the directory that was selected.

FileSelected

FileSelected(node, path)

Bases: Message

Posted when a file is selected.

Can be handled using on_directory_tree_file_selected in a subclass of DirectoryTree or in a parent widget in the DOM.

Parameters:

Name	Type	Description	Default
node	TreeNode[DirEntry]	The tree node for the file that was selected.	required
path	Path	The path of the file that was selected.	required

control property

control

The Tree that had a file selected.

node instance-attribute

node = node

The tree node of the file that was selected.

path instance-attribute

path = path

The path of the file that was selected.

clear_node

clear_node(node)

Clear all nodes under the given node.

Returns:

Type	Description
Self	The Tree instance.

filter_paths

filter_paths(paths)

Filter the paths before adding them to the tree.

Parameters:

Name	Type	Description	Default
paths	Iterable[Path]	The paths to be filtered.	required

Returns:

Type	Description
Iterable[Path]	The filtered paths.

By default this method returns all of the paths provided. To create a filtered DirectoryTree inherit from it and implement your own version of this method.

process_label

process_label(label)

Process a str or Text into a label. May be overridden in a subclass to modify how labels are rendered.

Parameters:

Name	Type	Description	Default
label	TextType	Label.	required

Returns:

Type	Description
Text	A Rich Text object.

reload

reload()

Reload the DirectoryTree contents.

Returns:

Type	Description
AwaitComplete	An optionally awaitable that ensures the tree has finished reloading.

reload_node

reload_node(node)

Reload the given node's contents.

The return value may be awaited to ensure the DirectoryTree has reached a stable state and is no longer performing any node reloading (of this node or any other nodes).

Parameters:

Name	Type	Description	Default
node	TreeNode[DirEntry]	The root of the subtree to reload.	required

Returns:

Type	Description
AwaitComplete	An optionally awaitable that ensures the subtree has finished reloading.

render_label

render_label(node, base_style, style)

Render a label for the given node.

Parameters:

Name	Type	Description	Default
node	TreeNode[DirEntry]	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_node

reset_node(node, label, data=None)

Clear the subtree and reset the given node.

Parameters:

Name	Type	Description	Default
node	TreeNode[DirEntry]	The node to reset.	required
label	TextType	The label for the node.	required
data	DirEntry | None	Optional data for the node.	None

Returns:

Type	Description
Self	The Tree instance.

validate_path

validate_path(path)

Ensure that the path is of the Path type.

Parameters:

Name	Type	Description	Default
path	str | Path	The path to validate.	required

Returns:

Type	Description
Path	The validated Path value.

Note

The result will always be a Python Path object, regardless of the value given.

watch_path async

watch_path()

Watch for changes to the path of the directory tree.

If the path is changed the directory tree will be repopulated using the new value as the root.