TreeView

TreeView is a feature-rich Go library for displaying and navigating tree structures in the terminal. TreeView has full Bubble Tea and Lipgloss support, allowing you to build glamorous, interactive terminal applications.

If you're upgrading from v1, the v2 update guide walks through the important changes and what to watch for.

Why TreeView?

What sets TreeView apart is its flexibility. You can build trees from any data source: flat lists with parent relationships, pre-nested hierarchical data, or create trees from your filesystem. The search and filtering system uses customizable predicates, giving you complete control over how users find what they're looking for. Search results automatically expand ancestor nodes so matches are visible, and the real-time filtering keeps the tree structure intact while hiding irrelevant items. When dealing with large trees, the bubbletea viewport support ensures smooth scrolling and focus. Navigation feels natural with keyboard bindings that you can customize to match your app's needs.

The styling system is particularly powerful. TreeView automatically detects file types and applies appropriate icons, but you can customize everything through the provider system to style any hierarchical with glamor. Whether you want subtle themes or vibrant, emoji-heavy displays, the Lipgloss integration makes it straightforward.

TreeView is ready for production. It provides proper error handling with sentinel errors, operations respect context cancellation and timeouts, and the library is thread-safe where it matters.

Examples

The examples directory contains twelve progressively complex demonstrations, from basic tree rendering to a fully-featured file browser. Each example includes comments and animated demos, so you can see exactly how to implement specific features in your own applications.

Basic Examples

Basic examples only demonstrate building and rendering a tree in the console.

Simple Tree
This example demonstrates the fundamental tree creation and rendering capabilities of the TreeView library.

Iterators
This example demonstrates how to range over a tree's nodes using the provided iterators.

Custom Styling
A showcase of the styling capabilities provided via lipgloss support

Comparison Display
This example demonstrates visualizing comparison operations with before and after displays.

Workflow Visualization
Example showing how to create domain-specific tree nodes for process and workflow tracking.

Build Trees From Parent Relationships
Shows how to use BuildTree to create trees from flat data structures where relationships are defined by parent ID references.

Build Trees From Hierarchical Data
Demonstrates using BuildTree for constructing trees from naturally hierarchical data structures.

Filesystem Builder
Demonstrates creating filesystem tree structures with NewTreeFromFileSystem constructor with support for special path characters like ., .., and ~. Shows path resolution, configurable depth limits, hidden file handling, and automatic file type detection for styling.

Intermediate Examples

Intermediate examples demonstrate treeview's full TUI support via BubbleTea.

Keyboard Controls
Advanced interactive example demonstrating comprehensive keyboard-based navigation within tree structures. Shows how to implement arrow key navigation, selection management, and basic searching.

Search & Filtering
This example demonstrates extending the search functionality to handle domain data.

Viewport Rendering
Demonstrates viewport-aware rendering for handling large tree structures. Solves the common problem of cursor navigation going off-screen in large directory trees by implementing automatic scrolling and responsive viewport management.

File Browser
Complete, terminal file browser application built with TreeView and Bubble Tea.

Contributing

Contributions are welcome! If you have any suggestions or encounter a bug, please open an issue or submit a pull request.

When contributing:

1. Fork the repository and create a new feature branch
2. Make your changes in a well-structured commit history
3. Include tests (when applicable)
4. Submit a pull request with a clear description of your changes

License

This project is licensed under the GNU Version 3 - see the LICENSE file for details.

Acknowledgments

TreeView is built on top of the excellent Charm ecosystem: - Bubble Tea for TUI framework - Lipgloss for styling and layout - VHS for epic scriptable demos - Charm community for inspiration and gif hosting!

Star History