TreePlugin

Tree Data Plugin for tbw-grid

Transforms your flat grid into a hierarchical tree view with expandable parent-child relationships. Ideal for file explorers, organizational charts, nested categories, or any data with a natural hierarchy.

Installation

import { TreePlugin } from '@toolbox-web/grid/plugins/tree';

CSS Custom Properties

Property	Default	Description
--tbw-tree-toggle-size	1.25em	Toggle icon width
--tbw-tree-indent-width	var(--tbw-tree-toggle-size)	Indentation per level
--tbw-tree-accent	var(--tbw-color-accent)	Toggle icon hover color
--tbw-animation-duration	200ms	Expand/collapse animation duration
--tbw-animation-easing	ease-out	Animation curve

Configuration Options

Option	Type	Description
childrenField?	string	Field name containing child rows (default: ‘children’)
autoDetect?	boolean	Auto-detect tree structure from data (default: true)
defaultExpanded?	boolean	Whether nodes are expanded by default (default: false)
indentWidth?	number	Indentation width per level in pixels (default: 20)
showExpandIcons?	boolean	Show expand/collapse icons (default: true)
treeColumn?	string	Field name of the column that displays the tree toggle and indentation. Defaults to the first visible column. Use this when the first column is narrow (e.g. an ID column) or when combining with pinned columns.
animation?	ExpandCollapseAnimation	Animation style for expanding/collapsing tree nodes. - false: No animation - 'slide': Slide animation (default) - 'fade': Fade animation

Examples

Basic Tree with Nested Children

import { queryGrid } from '@toolbox-web/grid';
import { TreePlugin } from '@toolbox-web/grid/plugins/tree';

const grid = queryGrid('tbw-grid');
grid.gridConfig = {
  columns: [
    { field: 'name', header: 'Name' },
    { field: 'type', header: 'Type' },
    { field: 'size', header: 'Size' },
  ],
  plugins: [new TreePlugin({ childrenField: 'children', indentWidth: 24 })],
};
grid.rows = [
  {
    id: 1,
    name: 'Documents',
    type: 'folder',
    children: [
      { id: 2, name: 'Report.docx', type: 'file', size: '24 KB' },
    ],
  },
];

Expanded by Default with Custom Animation

new TreePlugin({
  defaultExpanded: true,
  animation: 'fade', // 'slide' | 'fade' | false
  indentWidth: 32,
})

See Also

• TreeConfig for all configuration options
• FlattenedTreeRow for the flattened row structure

Extends BaseGridPlugin

Inherited methods like attach(), detach(), afterRender(), etc. are documented in the base class.

Properties

Property	Type	Description
manifest	PluginManifest	Plugin manifest - declares owned properties, config rules, and hook priorities.
dependencies	object[]	Optional dependency on MultiSort for coordinated sorting. When MultiSort is loaded, Tree defers header click sorting to it and queries the sort model in processRows. When MultiSort is absent, Tree uses its own sort state.

Property Details

manifest

Plugin manifest - declares owned properties, config rules, and hook priorities.

This is read by the configuration validator to:

• Validate that required plugins are loaded when their properties are used
• Execute configRules to detect invalid/conflicting settings
• Order hook execution based on priority

static override readonly manifest: PluginManifest<MyConfig> = {
  ownedProperties: [
    { property: 'myProp', level: 'column', description: 'the "myProp" column property' },
  ],
  configRules: [
    { id: 'myPlugin/conflict', severity: 'warn', message: '...', check: (c) => c.a && c.b },
  ],
};

---

Methods

detect()

detect(rows: readonly unknown[]): boolean

Parameters

Name	Type	Description
rows	readonly unknown[]

---

expand()

Expand a specific tree node, revealing its children.

If the node is already expanded, this is a no-op. Does not emit a tree-expand event (use toggle for event emission).

expand(key: string): void

Parameters

Name	Type	Description
key	string	The unique key of the node to expand (from FlattenedTreeRow.key)

Example

const tree = grid.getPluginByName('tree');
tree.expand('documents');          // Expand a root node
tree.expand('documents||reports');  // Expand a nested node

---

collapse()

Collapse a specific tree node, hiding its children.

If the node is already collapsed, this is a no-op. Does not emit a tree-expand event (use toggle for event emission).

collapse(key: string): void

Parameters

Name	Type	Description
key	string	The unique key of the node to collapse (from FlattenedTreeRow.key)

Example

const tree = grid.getPluginByName('tree');
tree.collapse('documents');

---

toggle()

Toggle the expanded state of a tree node.

If the node is expanded it will be collapsed, and vice versa. Emits a tree-expand event (broadcast to both DOM consumers and plugin bus).

toggle(key: string): void

Parameters

Name	Type	Description
key	string	The unique key of the node to toggle (from FlattenedTreeRow.key)

Example

const tree = grid.getPluginByName('tree');
tree.toggle('documents');  // Expand if collapsed, collapse if expanded

---

expandAll()

Expand all tree nodes recursively.

Every node with children will be expanded, revealing the full tree hierarchy. Emits a tree-expand plugin event.

expandAll(): void

Example

const tree = grid.getPluginByName('tree');
tree.expandAll();

---

collapseAll()

Collapse all tree nodes.

Every node will be collapsed, showing only root-level rows. Emits a tree-expand plugin event.

collapseAll(): void

Example

const tree = grid.getPluginByName('tree');
tree.collapseAll();

---

isExpanded()

Check whether a specific tree node is currently expanded.

isExpanded(key: string): boolean

Parameters

Name	Type	Description
key	string	The unique key of the node to check

Returns

boolean - true if the node is expanded, false otherwise

---

getExpandedKeys()

Get the keys of all currently expanded nodes.

Returns a snapshot copy — mutating the returned array does not affect the tree state.

getExpandedKeys(): string[]

Returns

string[] - Array of expanded node keys

Example

const tree = grid.getPluginByName('tree');
const keys = tree.getExpandedKeys();
localStorage.setItem('treeState', JSON.stringify(keys));

---

getFlattenedRows()

Get the flattened row model used for rendering.

Returns a snapshot copy of the internal flattened tree rows, including hierarchy metadata (depth, hasChildren, isExpanded, parentKey).

getFlattenedRows(): FlattenedTreeRow<TreeRow>[]

Returns

FlattenedTreeRow<TreeRow>[] - Array of FlattenedTreeRow objects

---

getRowMeta()

Get tree metadata (depth, key, hasChildren, isExpanded, parentKey) for a specific row reference. Returns undefined if the row is not part of the currently-flattened tree (e.g. collapsed under a parent or never processed).

Tree metadata lives in a parallel WeakMap keyed by row identity \u2014 it is NOT stored on the row object itself. This preserves the invariant that _rows[i] IS the user’s source row reference, so grid.updateRow(s) mutations survive the next ROWS-phase rebuild.

getRowMeta(row: TreeRow): FlattenedTreeRow<TreeRow> | undefined

Parameters

Name	Type	Description
row	TreeRow

Example

const tree = grid.getPluginByName('tree');
const meta = tree.getRowMeta(grid.rows[0]);
console.log(meta?.depth, meta?.hasChildren);

---

getRowByKey()

Look up an original row data object by its tree key.

getRowByKey(key: string): TreeRow | undefined

Parameters

Name	Type	Description
key	string	The unique key of the node

Returns

TreeRow | undefined - The original row data, or undefined if not found

---

expandToKey()

Expand all ancestor nodes of the target key, revealing it in the tree.

Useful for “scroll to node” or search-and-reveal scenarios where a deeply nested node needs to be made visible.

expandToKey(key: string): void

Parameters

Name	Type	Description
key	string	The unique key of the node to reveal

Example

const tree = grid.getPluginByName('tree');
// Reveal a deeply nested node by expanding all its parents
tree.expandToKey('root||child||grandchild');

---