filetree

README

File tree

Interactive directory tree with expand/collapse, vim-style navigation, and multi-select.

Install

glyph add file-tree

This copies file-tree.go (and its test file) into your repo at the path your glyph.json aliases declare. After install, the file is yours: edit it, refactor it, rename it. There is no file-tree library to keep in sync.

Hello, world

package main

import (
	"fmt"

	tea "github.com/charmbracelet/bubbletea"

	filetree "github.com/truffle-dev/glyph/components/file-tree"
)

type model struct{ t filetree.Model }

func (m model) Init() tea.Cmd { return nil }
func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
	if k, ok := msg.(tea.KeyMsg); ok && k.String() == "q" {
		return m, tea.Quit
	}
	updated, cmd := m.t.Update(msg)
	m.t = updated
	return m, cmd
}
func (m model) View() string { return m.t.View() }

func main() {
	root := filetree.Node{
		Name: "src",
		Children: []filetree.Node{
			{Name: "main.go"},
			{Name: "internal", Children: []filetree.Node{
				{Name: "store.go"},
			}},
		},
	}
	if _, err := tea.NewProgram(model{t: filetree.New(root)}).Run(); err != nil {
		fmt.Println(err)
	}
}

API surface

Package: filetree

Types

• Node — directory or leaf in the tree
• Model — Bubble Tea model
• SelectMsg — emitted on expand/collapse/leaf-Enter

Functions

• New

Model methods

• Init, Update, View
• WithTitle, WithMultiSelect
• Selected, SelectedNode, IsSelected, SelectedPaths
• Expand, Collapse, SetCursor

Dependencies

• glyph component theme (installed automatically)
• github.com/charmbracelet/bubbletea@v1.3.10
• github.com/charmbracelet/lipgloss@v1.1.0

Notes

The model holds a flat slice of visible rows that's rebuilt every time you expand or collapse a directory. Bindings: ↑↓ or j/k for cursor, → or l to expand a directory, ← or h to collapse-or-jump-to-parent, Enter to toggle a directory or select a leaf, Space to toggle multi-select (when enabled via WithMultiSelect(true)).

Wire SelectMsg into a parent Update to drive a sibling pane. The examples/file-explorer demo uses it to swap the code preview when you navigate.

See also

• examples/file-explorer — full IDE-style surface using file-tree, breadcrumb, and code-view
• components/file-tree/story — runnable story binary (go run -tags glyph_story ./components/file-tree/story/)
• registry manifest — the JSON contract glyph add reads

License

MIT, same as the rest of glyph.

Documentation

Overview

Package filetree renders an interactive directory tree.

The model holds a flat slice of visible nodes and tracks the cursor, the set of expanded directories, and an optional selection set for multi-select operations. Expand/collapse, navigation, and selection all run through the standard Bubble Tea Update loop.

The tree is constructed from a nested Node literal; consumers own the data shape, so the same component renders a project file system, a JSON document, a Linear/Notion outline, or anything else with a directory analogy.

Index

• type Model
  • func New(root Node) Model
  • func (m *Model) Collapse(path string)
  • func (m *Model) Expand(path string)
  • func (m Model) Init() tea.Cmd
  • func (m Model) IsSelected(path string) bool
  • func (m Model) Selected() string
  • func (m Model) SelectedNode() (Node, bool)
  • func (m Model) SelectedPaths() []string
  • func (m *Model) SetCursor(path string)
  • func (m Model) Update(msg tea.Msg) (Model, tea.Cmd)
  • func (m Model) View() string
  • func (m Model) WithMultiSelect(b bool) Model
  • func (m Model) WithTitle(t string) Model
• type Node
  • func (n Node) IsDir() bool
• type SelectMsg

Types

type Model

type Model struct {
	Root  Node
	Title string
	// contains filtered or unexported fields
}

Model is the Bubble Tea state of the file tree.

func New

func New(root Node) Model

New constructs a Model with the root expanded.

func (*Model) Collapse

func (m *Model) Collapse(path string)

Collapse removes a directory from the expanded set and rebuilds.

func (*Model) Expand

func (m *Model) Expand(path string)

Expand marks a directory open and rebuilds the visible slice.

func (Model) Init

func (m Model) Init() tea.Cmd

Init implements tea.Model.

func (Model) IsSelected

func (m Model) IsSelected(path string) bool

IsSelected reports whether the given path is in the multi-select set.

func (Model) Selected

func (m Model) Selected() string

Selected returns the slash-joined path under the cursor, or "" if the tree is empty.

func (Model) SelectedNode

func (m Model) SelectedNode() (Node, bool)

SelectedNode returns the Node under the cursor; second value is false when the tree is empty.

func (Model) SelectedPaths

func (m Model) SelectedPaths() []string

SelectedPaths returns paths in the multi-select set, sorted by visible order.

func (*Model) SetCursor

func (m *Model) SetCursor(path string)

SetCursor moves the cursor to the row whose path matches; no-op if absent.

func (Model) Update

func (m Model) Update(msg tea.Msg) (Model, tea.Cmd)

Update handles arrow keys, expand/collapse (right/left or l/h), and Enter / space.

func (Model) View

func (m Model) View() string

View renders the tree. Title (if set) is on the first line, followed by visible rows. Long names are truncated to width-3 with an ellipsis.

func (Model) WithMultiSelect

func (m Model) WithMultiSelect(b bool) Model

WithMultiSelect enables space-toggle selection.

func (Model) WithTitle

func (m Model) WithTitle(t string) Model

WithTitle sets a header line shown above the tree.

type Node

type Node struct {
	Name     string
	Children []Node
	// Icon overrides the default folder/file glyph. Optional.
	Icon string
	// Meta is appended muted to the right of Name (e.g. "12kb", "modified").
	Meta string
}

Node is a directory or leaf in the tree. Children make a node a directory.

func (Node) IsDir

func (n Node) IsDir() bool

IsDir reports whether the node is a directory.

type SelectMsg

type SelectMsg struct {
	Path  string
	IsDir bool
}

SelectMsg fires when the user presses Enter on a leaf (file) or when a directory is opened/closed. Path is the slash-joined path from the root.