FileTreeExplorer

Tree view specialized for file/directory nodes with icons and optional git status.

Usage

ui.fileTreeExplorer({
  id: "explorer",
  data: state.data,
  expanded: state.expanded,
  selected: state.selected,
  showIcons: true,
  showStatus: true,
  onChange: (node, expanded) => toggleNode(node, expanded),
  onSelect: (node) => selectNode(node),
  onPress: (node) => openNode(node),
})

Props

Prop	Type	Default	Description
`id`	`string`	required	Widget identifier
`data`	`FileNode \| FileNode[]`	required	Tree data (no filesystem access in core)
`expanded`	`string[]`	required	Expanded node paths
`selected`	`string`	-	Selected node path
`focused`	`string`	-	Focused node path
`showIcons`	`boolean`	`true`	Show file icons
`showStatus`	`boolean`	`true`	Show git status indicators
`indentSize`	`number`	`2`	Indentation per depth level
`onChange`	`(node, expanded) => void`	required	Expand/collapse callback
`onSelect`	`(node) => void`	required	Selection callback
`onPress`	`(node) => void`	required	Activate callback (Enter/double-click)
`onContextMenu`	`(node) => void`	-	Context menu callback for right-click mouse routing
`focusConfig`	`FocusConfig`	-	Control focus visuals; `{ indicator: "none" }` suppresses row highlight
`renderNode`	`(node, depth, state) => VNode`	-	Custom row renderer; replaces the built-in icon/status/name line

Behavior

Keyboard

Arrow keys navigate. Enter activates the focused node.

Mouse

Left click on a node calls onSelect(node) immediately on mouse down, moving selection to that node.
Double-click (two clicks within 500ms on the same node) calls onPress(node) on mouse up. For directory nodes, apps typically toggle expand/collapse; for files, apps open the file.
Right click on a node calls onContextMenu(node) when provided.
Wheel scroll moves the visible row window when the explorer content overflows the viewport.
Mouse click routing follows the same press/release model as the Table widget: mouse down captures the target node index, mouse up verifies the same node was hit before firing activation.

Notes

FileNode includes name, path, type, and optional children and status.
status values: "modified", "staged", "untracked", "deleted", "renamed".
showIcons and showStatus only affect the built-in row renderer.
renderNode(node, depth, state) replaces the built-in row content entirely and receives row metadata for expanded, selected, focused, and hasChildren.
The core renderer wires onContextMenu from right-click mouse input; it does not currently register a dedicated keyboard Menu-key handler.

Focus Control

By default, the focused node row is highlighted with the theme's info color. To suppress this (e.g., when the tree is inside a pane with its own active/inactive border chrome), use focusConfig:

ui.fileTreeExplorer({
  id: "explorer",
  data: state.data,
  expanded: state.expanded,
  focusConfig: { indicator: "none" },
  onChange: handleToggle,
  onSelect: handleSelect,
  onPress: handleActivate,
})

See Focus Styles for details on focusConfig.

File picker
Tree
Focus Styles - Per-widget focus control
Mouse Support - Mouse routing details

FileTreeExplorer

On this page