Skip to content

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:

DirectoryTreeApp 📂  ┣━━ 📁 __pycache__ ┣━━ 📁 dist ┣━━ 📁 docs ┣━━ 📁 examples ┣━━ 📁 imgs ┣━━ 📁 notes ┣━━ 📁 questions ┣━━ 📁 reference ┣━━ 📁 sandbox ┣━━ 📁 site ┣━━ 📁 src ┣━━ 📁 tests ┣━━ 📁 tools ┣━━ 📄 CHANGELOG.md ┣━━ 📄 CODE_OF_CONDUCT.md ┣━━ 📄 CONTRIBUTING.md▄▄ ┣━━ 📄 docs.md ┣━━ 📄 faq.yml ┣━━ 📄 keys.log ┣━━ 📄 LICENSE ┣━━ 📄 Makefile ┣━━ 📄 mkdocs-common.yml ┣━━ 📄 mkdocs-nav-offline.yml

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

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.