API reference.

TreeView

TreeView creates the canvas, filter control, editor and tooltip inside a host element. Give that element a height. The package is JavaScript ESM with bundled declarations for editor autocomplete. The element, canvas, controller and destroyed properties expose the mounted view state.

import { TreeView } from 'virtual-tree-canvas';

const view = new TreeView(host, { filter: true, initialExpandDepth: 2 });
view.setData(nodes);
view.on('selectionchange', ({ detail }) => console.log(detail.selection));
// On permanent unmount: view.destroy();

Configuration options

Pass these to the constructor or view.configure(options). The component defaults to one selected row, an editable tree and a visible filter.

Rows, live values, search and filtering

For setData, each row needs a stable id. Use parentId for children. Optional row fields include label, type, icon, image, tags, data and reorderable. Dynamic patches have an id and a state object, such as { id: 'btc', state: { value: 42 } }.

The built-in filter is enabled by default and keeps matching descendants visible with their ancestors. Search highlights matches and can move focus. Use filtering to narrow the visible tree; use search to navigate results. Compare the bar above the large tree and the header filter in the units table.

view.setFilter('radar');
view.setFilter('radar', { caseSensitive: true, wholeWord: true });
view.setFilter((node, state) => state.status === 'warning');
view.clearFilter();

view.search('radar');
view.nextSearchResult();
view.clearSearch();

Columns, sorting and themes

Use builtInColumns or define columns with id, label, width, minWidth, align, kind and sortable. Kinds include tree, status, value, progress, type, updated and text. value(node, state) supplies the raw value; format(value, node, state) changes displayed text and tooltips without changing sort order. render(ctx, cell) draws custom Canvas2D content.

Sorting orders siblings within their parent, preserving the hierarchy. Click a heading to cycle ascending, descending and unsorted, or use view.controller.sortBy(id, direction). The raw value is compared, so formatting a number as a string does not turn numeric sorting into lexical sorting.

import { builtInColumns, lightTheme } from 'virtual-tree-canvas';

view.setColumns([
  builtInColumns.tree,
  {
    id: 'change', label: '24h %', kind: 'value', width: 90,
    value: (_node, state) => state.change,
    valueType: (value) => value > 0 ? 'positive' : value < 0 ? 'negative' : 'neutral',
    format: (value) => `${value.toFixed(2)}%`
  }
]);
view.setTheme({ ...lightTheme, valueColors: {
  ...lightTheme.valueColors, positive: '#15803d', negative: '#be123c'
} });

valueType can be a fixed semantic name or a callback. Its colour comes from theme.valueColors; it does not change formatting or sorting. Built-in darkTheme and lightTheme are available, and theme.statuses customizes status pills.

Column helpers include builtInColumns, defaultTreeTableColumns() and inspectorColumns(). For icons, builtinIconNames lists bundled names. registerIcon() accepts a custom source; iconsBaseUrl points to a replacement SVG directory. Applications sharing icons across views can supply an IconRegistry and use its register(), get(), prepare() and draw() methods.

Object inspector metadata

setModel(model, meta?) makes property rows from an object or array. No IDs are required. Metadata keys are property paths such as 'sensor.range' or wildcard paths such as 'tracks.*.speed'. Use presentation: 'pane' for compact controls or 'table' for Property / Value columns.

Array items use compact indexed rows; primitive values edit in the row, while objects and nested arrays expand. The inspector emits valuechange for a value edit, modelchange for model changes and action for metadata buttons.

Selection, order, actions and data drag

Selection is single row by default. With multiSelect: true, Ctrl/Command + click toggles rows, Shift + click selects a range, and Shift + drag selects a visible range. An ordinary click still selects one row.

The component emits drag events with the selected items, nodeIds and pointer event. Your application decides where a drop is valid and updates its data. See the two-tree transfer example.

Events

Subscribe with view.on(type, listener). Each listener receives an event whose payload is event.detail. Unsubscribe with the function returned by on, or use off.

Lower-level controller

Use TreeViewController when your application already owns the canvas and render loop. view.controller exposes the same controller inside a TreeView. Methods shared with TreeView work on both; the controller also provides the operations below.

import { TreeViewController } from 'virtual-tree-canvas';

const tree = new TreeViewController({ canvas, host, autoRender: true });
tree.setData(nodes);
tree.sortBy('value', 'asc');
// On permanent unmount: tree.destroy();

The large-tree demo exercises asynchronous filtering and exposes live render metrics. The inspector demo shows the pane and table presentations.