TreeSelect

TreeSelect is a generic tree selection component available with the tree feature. It reuses TreeItem and TreeState from tui-tree-widget, and only captures hierarchical navigation, collapse/expand, confirm selection, and input exclusivity. It does not bind itself to files, directories, or any other business meaning.

tree select demo

This recording is generated by docs/tapes/tree-select.tape. The example defaults to components/select, moves to multi-select with j, submits with Enter, goes back to the parent node to collapse/expand, and finally switches to the empty-tree state.

Run

cargo run --example tree_select

Press h/l to collapse or expand, j/k to move, Space to toggle the current node, Enter to submit, e to toggle the empty tree, and q to quit.

Feature

TreeSelect is behind the tree feature:

ratatui-kit = { version = "...", features = ["tree"] }

Examples use the full feature, so they can be run directly. The library has an intentionally empty default feature set; a bare cargo check will not compile the tree component.

Minimal form

use ratatui_kit::components::tui_tree_widget::TreeItem;

TreeSelect<&'static str>(
    active: true,
    items: demo_items(),
    default_selection: vec!["components", "select"],
    highlight_symbol: "> ",
    node_closed_symbol: "+ ",
    node_open_symbol: "- ",
    on_select: move |id: &'static str| {
        submitted.set(format!("selected {id}"));
    },
)

default_selection is not an index; it is a node path. For a default path like components/select, the component selects select and opens its ancestor node components, making the default item visible on the first frame.

TreeItem

The T in TreeItem<T> is the node identifier, not display text. Identifiers only need to be unique within the same level, and on_select returns the final identifier in the current path.

fn demo_items() -> Vec<TreeItem<'static, &'static str>> {
    vec![
        branch(
            "components",
            "Components",
            vec![
                TreeItem::new_leaf("search-input", "SearchInput"),
                TreeItem::new_leaf("select", "Select"),
                TreeItem::new_leaf("multi-select", "MultiSelect"),
                TreeItem::new_leaf("tree-select", "TreeSelect"),
            ],
        ),
    ]
}

The framework does not put business types such as PathBuf, file extensions, or section IDs into the component API. For file trees, directory trees, or chapter trees, convert business data to TreeItem<T> in your application layer.

External state

By default, TreeSelect stores its own TreeState<T>. If the page needs to show the current path, reset across components, or keep state outside a modal, pass external state:

let tree_state = hooks.use_state(TreeState::<&'static str>::default);
let path = path_label(tree_state.read().selected());

TreeSelect<&'static str>(
    state: tree_state,
    items: items,
    default_selection: default_selection,
    on_select: move |id| {
        submitted.set(format!("selected {id}"));
    },
)

TreeState::selected() returns the full path slice, for example ["components", "select"]. on_select on Enter returns only the current node id; if business code needs the full path, read it directly from the external TreeState.

Input and empty state

TreeSelect uses an EventScope::Current handler:

h / Left: collapse the current node or move back to the parent.
l / Right: expand the current node.
j/k / Down/Up: move among visible nodes.
Space: toggle the current node’s expanded state.
Enter: submit the current node.

When active: false, it does not handle events. When items is empty, it also does not consume tree-navigation keys, so the parent can still handle page-level shortcuts such as e and q in the example.

Layout and style

TreeSelect can receive width, height, margin, and offset directly. Its border still uses the native Block from tui-tree-widget, keeping the wrapper thin:

TreeSelect<&'static str>(
    width: Constraint::Length(40),
    block: Block::bordered()
        .border_style(Style::new().fg(Color::Cyan))
        .title_top(Line::from(" component map ").centered()),
    highlight_style: Style::new().fg(Color::Black).bg(Color::Green),
)

To put it in a modal, render it directly in the Modal subtree. Its Current handler belongs to the modal input layer, so components behind the modal do not process the same keys. For ordinary single-select, see Select; for ordinary multi-select, see MultiSelect; for long lists and custom rows, see VirtualList.