ink-tree-view

A tree view component for Ink (React for CLIs). Display hierarchical data with expand/collapse, keyboard navigation, selection modes, custom rendering, virtual scrolling, and async lazy loading.

Features

• Hierarchical data display with expand/collapse
• Full keyboard navigation (arrows, Home/End, PageUp/PageDown, Enter, Space)
• Controlled or uncontrolled expansion, selection, and focus
• Selection modes: none, single, and multiple (with checkboxes)
• Custom node rendering via renderNode prop
• Virtual scrolling for large trees (visibleNodeCount)
• Async/lazy-loaded children via loadChildren + isParent
• Error handling for failed async loads via onLoadError
• Headless hooks (useTreeViewState, useTreeView) for full control
• TypeScript-first with complete type exports

Install

npm install ink-tree-view

Peer dependencies: ink (>=6.0.0), react (>=19.0.0). Requires Node.js >=20.

Quick Start

import {render} from 'ink';
import {TreeView} from 'ink-tree-view';

const data = [
  {
    id: 'src',
    label: 'src',
    children: [
      {id: 'index', label: 'index.ts'},
      {
        id: 'components',
        label: 'components',
        children: [
          {id: 'button', label: 'button.tsx'},
          {id: 'input', label: 'input.tsx'},
        ],
      },
    ],
  },
  {id: 'readme', label: 'README.md'},
  {id: 'package', label: 'package.json'},
];

render(<TreeView data={data} />);

Use arrow keys to navigate, Right to expand, Left to collapse, and Enter to toggle.

Data Model

Tree data is an array of TreeNode<T> objects. Each node must have a unique id across the entire tree.

type TreeNode<T = Record<string, unknown>> = {
  /** Unique identifier. Must be unique across the entire tree. */
  id: string;
  /** Display label used by the default renderer. */
  label: string;
  /** Arbitrary user data attached to this node. */
  data?: T;
  /** Child nodes. Undefined or empty array means leaf node. */
  children?: Array<TreeNode<T>>;
  /** Mark as a parent whose children will be loaded via loadChildren. */
  isParent?: boolean;
};

Example with custom data

type FileInfo = {size: number; modified: string};

const data: TreeNode<FileInfo>[] = [
  {
    id: 'doc',
    label: 'document.pdf',
    data: {size: 1024, modified: '2025-01-15'},
  },
];

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | data | TreeNode<T>[] | required | Array of root-level tree nodes. | | selectionMode | 'none' \| 'single' \| 'multiple' | 'none' | Selection behavior. 'single' allows one selected node; 'multiple' shows checkboxes. | | defaultExpanded | ReadonlySet<string> \| 'all' | undefined | Node IDs expanded on mount (uncontrolled), or 'all' to expand everything. | | defaultSelected | ReadonlySet<string> | undefined | Node IDs selected on mount (uncontrolled, ignored in 'none' mode). | | expanded | ReadonlySet<string> | undefined | Controlled expanded set. When set, the tree is controlled: keys report intent via onExpandChange and this prop is authoritative. | | selected | ReadonlySet<string> | undefined | Controlled selected set. When set, selection is controlled via onSelectChange. | | focusedId | string | undefined | Controlled focused node ID. When set, focus is controlled via onFocusChange. | | visibleNodeCount | number | Infinity | Max visible rows. Enables virtual scrolling when finite. Recommended for large trees (see Virtual Scrolling). | | renderNode | (props: TreeNodeRendererProps<T>) => ReactNode | undefined | Custom renderer for each node. Receives {node, state}. | | loadChildren | (node: TreeNode<T>) => Promise<TreeNode<T>[]> | undefined | Async loader called when expanding an isParent: true node. | | onLoadError | (nodeId: string, error: Error) => void | undefined | Called when loadChildren rejects. Loading state is cleared so the user can retry. | | onFocusChange | (nodeId: string) => void | undefined | Called when the focused node changes (not on initial mount). | | onExpandChange | (expandedIds: ReadonlySet<string>) => void | undefined | Called when the set of expanded nodes changes. | | onSelectChange | (selectedIds: ReadonlySet<string>) => void | undefined | Called when the selection changes. | | isDisabled | boolean | false | When true, all keyboard input is ignored. |

Keyboard Shortcuts

| Key | Action | |-----|--------| | Up Arrow | Move focus to the previous visible node | | Down Arrow | Move focus to the next visible node | | Right Arrow | Expand focused node, or move to first child if already expanded. Triggers async load for isParent nodes. | | Left Arrow | Collapse focused node, or move to parent if already collapsed | | Enter | Toggle expand/collapse ('none' mode) or select ('single'/'multiple' mode) | | Space | Toggle expand/collapse ('none'/'single' mode) or toggle selection ('multiple' mode) | | Home | Jump to the first node | | End | Jump to the last node | | Page Up | Move focus up by one viewport page | | Page Down | Move focus down by one viewport page |

Custom Rendering

Use the renderNode prop to completely control how each node looks.

import {Box, Text} from 'ink';
import {TreeView, type TreeNodeRendererProps} from 'ink-tree-view';

type FileData = {size: number};

function CustomNode({node, state}: TreeNodeRendererProps<FileData>) {
  const prefix = state.hasChildren
    ? state.isExpanded ? 'v ' : '> '
    : '  ';

  return (
    <Box>
      <Text dimColor={!state.isFocused}>
        {'  '.repeat(state.depth)}
        {prefix}
        {node.label}
      </Text>
      {node.data && (
        <Text color="gray"> ({node.data.size} bytes)</Text>
      )}
      {state.isSelected && <Text color="green"> [selected]</Text>}
    </Box>
  );
}

render(
  <TreeView<FileData>
    data={data}
    selectionMode="single"
    renderNode={CustomNode}
  />
);

TreeNodeRendererProps<T> includes:

• node -- the TreeNode<T> data
• state -- a TreeNodeState with: isFocused, isExpanded, isSelected, depth, hasChildren, isLoading

Selection Modes

No selection (default)

<TreeView data={data} />

Enter and Space toggle expand/collapse.

Single selection

<TreeView
  data={data}
  selectionMode="single"
  onSelectChange={(selectedIds) => {
    const selected = [...selectedIds][0];
    console.log('Selected:', selected);
  }}
/>

Enter selects the focused node. Only one node can be selected at a time.

Multiple selection

<TreeView
  data={data}
  selectionMode="multiple"
  defaultSelected={new Set(['node-1', 'node-3'])}
  onSelectChange={(selectedIds) => {
    console.log('Selected:', [...selectedIds]);
  }}
/>

Enter and Space toggle selection on the focused node. Checkboxes appear next to each node.

Controlled Mode

By default the tree is uncontrolled: it manages its own expansion, selection, and focus, seeded by defaultExpanded / defaultSelected. Pass the controlled counterparts (expanded, selected, focusedId) to take ownership of that state instead. This follows the standard React controlled/uncontrolled pattern: when a controlled prop is present, keypresses report intent through the matching callback (onExpandChange, onSelectChange, onFocusChange) and the prop stays authoritative until you update it.

import {useState} from 'react';
import {TreeView} from 'ink-tree-view';

function ControlledTree({data}) {
  const [expanded, setExpanded] = useState(new Set<string>());
  const [selected, setSelected] = useState(new Set<string>());

  return (
    <TreeView
      data={data}
      selectionMode="multiple"
      expanded={expanded}
      selected={selected}
      onExpandChange={ids => setExpanded(new Set(ids))}
      onSelectChange={ids => setSelected(new Set(ids))}
    />
  );
}

Mix and match: control only selected while leaving expansion uncontrolled, or vice versa. Any prop you omit keeps its uncontrolled behavior.

Virtual Scrolling

For large trees, set visibleNodeCount to limit the number of visible rows. The viewport scrolls to keep the focused node in view, and scroll indicators appear when content extends beyond the viewport.

<TreeView
  data={largeTree}
  defaultExpanded="all"
  visibleNodeCount={15}
/>

Performance: visibleNodeCount defaults to Infinity, which renders every visible node. Individual rows are memoized so a keypress only re-renders the rows whose state actually changed, but for large, fully-expanded trees you should still set a finite visibleNodeCount so only a windowed slice is rendered at all.

Async Children

Use loadChildren to lazily load children when a node is first expanded. Mark on-demand nodes with isParent: true. A loading indicator is shown while the request is in progress.

async function fetchChildren(node) {
  const response = await fetch(`/api/tree/${node.id}/children`);
  return response.json();
}

const data = [
  {id: 'root', label: 'Root', isParent: true},
  {id: 'leaf', label: 'Leaf'},
];

render(
  <TreeView
    data={data}
    loadChildren={fetchChildren}
    onLoadError={(nodeId, error) => {
      console.error(`Failed to load children for ${nodeId}:`, error.message);
    }}
  />
);

When loadChildren rejects, onLoadError fires and the loading state is cleared so the user can retry by pressing Right Arrow again.

Hooks API

For headless/custom usage, two hooks are exported directly.

useTreeViewState<T>(props)

Manages all tree state: focus, expansion, selection, viewport scrolling, and loading.

import {useTreeViewState} from 'ink-tree-view';

const state = useTreeViewState({
  data,
  selectionMode: 'multiple',
  defaultExpanded: new Set(['root']),
  visibleNodeCount: 10,
  onFocusChange: (id) => { /* ... */ },
  onExpandChange: (ids) => { /* ... */ },
  onSelectChange: (ids) => { /* ... */ },
});

Returned state:

| Property | Type | Description | |----------|------|-------------| | focusedId | string \| undefined | Currently focused node ID | | expandedIds | ReadonlySet<string> | Set of expanded node IDs | | selectedIds | ReadonlySet<string> | Set of selected node IDs | | viewportNodes | Array<{node, state}> | Nodes in current viewport | | visibleCount | number | Total visible node count | | hasScrollUp | boolean | Nodes exist above the viewport | | hasScrollDown | boolean | Nodes exist below the viewport | | loadingIds | ReadonlySet<string> | Currently loading node IDs | | nodeMap | TreeNodeMap<T> | Underlying data structure |

Actions:

| Method | Description | |--------|-------------| | focusNext() | Move focus down | | focusPrevious() | Move focus up | | focusFirst() | Jump to first node | | focusLast() | Jump to last node | | focusPageDown() | Move focus down by one viewport page | | focusPageUp() | Move focus up by one viewport page | | expand() | Expand focused node | | expandNode(id) | Expand a specific node | | collapse() | Collapse focused node | | collapseNode(id) | Collapse a specific node | | toggleExpanded() | Toggle expand/collapse on focused node | | expandAll() | Expand all nodes | | collapseAll() | Collapse all nodes | | select() | Select/deselect focused node | | focusParent() | Move focus to parent | | focusFirstChild() | Move focus to first child | | setLoading(id, bool) | Mark a node as loading | | setChildrenError(id) | Clear loading state after failure | | insertChildren(parentId, children) | Insert children under a parent |

useTreeView<T>(props)

Wires keyboard input to a TreeViewState instance. Call this after useTreeViewState to enable keyboard navigation.

import {Box, Text} from 'ink';
import {useTreeViewState, useTreeView} from 'ink-tree-view';

function MyTree({data}) {
  const state = useTreeViewState({data});

  useTreeView({
    state,
    selectionMode: 'none',
    loadChildren: async (node) => {
      // fetch children...
    },
  });

  return (
    <Box flexDirection="column">
      {state.viewportNodes.map(({node, state: ns}) => (
        <Text key={node.id} bold={ns.isFocused}>
          {'  '.repeat(ns.depth)}{node.label}
        </Text>
      ))}
    </Box>
  );
}

TypeScript

All types are exported from the package entry point:

import type {
  TreeNode,
  TreeNodeState,
  SelectionMode,
  AsyncChildrenFn,
  TreeViewProps,
  TreeNodeRendererProps,
  TreeViewState,
  UseTreeViewStateProps,
  UseTreeViewProps,
  TreeViewTheme,
  FlatNode,
} from 'ink-tree-view';

import {
  TreeView,
  useTreeViewState,
  useTreeView,
  treeViewTheme,
  TreeNodeMap,
} from 'ink-tree-view';

Contributing

Contributions are welcome. Please open an issue to discuss your idea before submitting a PR.

git clone https://github.com/costajohnt/ink-tree-view.git
cd ink-tree-view
npm install
npm test

Run npm run build to compile and npm run typecheck to verify types.

Changelog

See GitHub Releases.

License

MIT -- Copyright (c) 2024-2026 John Costa