TermUI.Widgets.TreeView (TermUI v0.2.0)

View Source

TreeView widget for displaying hierarchical data with expand/collapse.

TreeView renders a tree structure with indentation, supporting lazy loading for large trees, keyboard navigation, single/multi-selection, and search filtering.

Usage

TreeView.new(
  nodes: [
    TreeView.node(:root, "Root", children: [
      TreeView.node(:child1, "Child 1"),
      TreeView.node(:child2, "Child 2", children: [
        TreeView.node(:grandchild, "Grandchild")
      ])
    ])
  ],
  on_select: fn node -> handle_select(node) end,
  on_expand: fn node -> load_children(node) end
)

Node Structure

Nodes are maps with:

  • :id - Unique identifier (required)
  • :label - Display text (required)
  • :icon - Optional icon string
  • :children - List of child nodes, :lazy for on-demand loading, or nil for leaf
  • :disabled - Whether node is disabled
  • :metadata - User-defined data

Keyboard Navigation

  • Up/Down: Move cursor between visible nodes
  • Left: Collapse node or move to parent
  • Right: Expand node or move to first child
  • Enter/Space: Toggle expand or select
  • Home/End: Jump to first/last visible node
  • PageUp/PageDown: Jump by page
  • Ctrl+A: Select all (multi-select mode)
  • Shift+Up/Down: Extend selection (multi-select mode)
  • /: Start search filter
  • Escape: Clear filter or deselect

Summary

Types

node_id()
tree_node()

Functions

branch(id, label, children, opts \\ [])

Creates a branch node with children.

clear_filter(state)

Clears the filter.

clear_selection(state)

Clears the selection.

collapse(state, node_id)

Collapses a node by ID.

collapse_all(state)

Collapses all nodes.

expand(state, node_id)

Expands a node by ID.

expand_all(state)

Expands all nodes.

finish_loading(state, node_id)

Marks a node as finished loading (clears loading state).

get_expanded(state)

Gets the expanded node IDs.

get_focused(state)

Gets the currently focused node.

get_selected(state)

Gets the currently selected node IDs.

lazy(id, label, opts \\ [])

Creates a lazy-loading node.

leaf(id, label, opts \\ [])

Creates a leaf node (no children).

new(opts)

Creates new TreeView widget props.

node(id, label, opts \\ [])

Creates a tree node.

set_children(state, node_id, children)

Updates the children of a node (for lazy loading).

set_filter(state, filter)

Sets the filter programmatically.

set_selected(state, node_ids)

Sets the selection programmatically.

Types

node_id()

@type node_id() :: term()

tree_node()

@type tree_node() :: %{
  id: node_id(),
  label: String.t(),
  icon: String.t() | nil,
  children: [tree_node()] | :lazy | nil,
  disabled: boolean(),
  metadata: map()
}

Functions

branch(id, label, children, opts \\ [])

@spec branch(node_id(), String.t(), [tree_node()], keyword()) :: tree_node()

Creates a branch node with children.

clear_filter(state)

@spec clear_filter(map()) :: map()

Clears the filter.

clear_selection(state)

@spec clear_selection(map()) :: map()

Clears the selection.

collapse(state, node_id)

@spec collapse(map(), node_id()) :: map()

Collapses a node by ID.

collapse_all(state)

@spec collapse_all(map()) :: map()

Collapses all nodes.

expand(state, node_id)

@spec expand(map(), node_id()) :: map()

Expands a node by ID.

expand_all(state)

@spec expand_all(map()) :: map()

Expands all nodes.

finish_loading(state, node_id)

@spec finish_loading(map(), node_id()) :: map()

Marks a node as finished loading (clears loading state).

get_expanded(state)

@spec get_expanded(map()) :: MapSet.t(node_id())

Gets the expanded node IDs.

get_focused(state)

@spec get_focused(map()) :: tree_node() | nil

Gets the currently focused node.

get_selected(state)

@spec get_selected(map()) :: MapSet.t(node_id())

Gets the currently selected node IDs.

lazy(id, label, opts \\ [])

@spec lazy(node_id(), String.t(), keyword()) :: tree_node()

Creates a lazy-loading node.

leaf(id, label, opts \\ [])

@spec leaf(node_id(), String.t(), keyword()) :: tree_node()

Creates a leaf node (no children).

new(opts)

@spec new(keyword()) :: map()

Creates new TreeView widget props.

Options

  • :nodes - List of root nodes (required)
  • :on_select - Callback when node is selected: fn node -> ... end

  • :on_expand - Callback when node is expanded: fn node -> children | :loading end

  • :on_collapse - Callback when node is collapsed: fn node -> ... end
  • :selection_mode - :single, :multi, or :none (default: :single)
  • :show_root - Show root nodes (default: true)
  • :indent_size - Characters per indent level (default: 2)
  • :icons - Icon configuration map
  • :initially_expanded - List of node IDs to expand initially
  • :initially_selected - List of node IDs to select initially

node(id, label, opts \\ [])

@spec node(node_id(), String.t(), keyword()) :: tree_node()

Creates a tree node.

Options

  • :children - Child nodes, :lazy for on-demand loading, or omit for leaf
  • :icon - Custom icon string
  • :disabled - Whether node is disabled (default: false)
  • :metadata - User-defined data map

set_children(state, node_id, children)

@spec set_children(map(), node_id(), [tree_node()]) :: map()

Updates the children of a node (for lazy loading).

set_filter(state, filter)

@spec set_filter(map(), String.t() | nil) :: map()

Sets the filter programmatically.

set_selected(state, node_ids)

@spec set_selected(map(), [node_id()]) :: map()

Sets the selection programmatically.