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';

Configuration Options

Option	Type	Default	Description
childrenField	string	'children'	Field containing child array
autoDetect	boolean	true	Auto-detect tree structure from data
defaultExpanded	boolean	false	Expand all nodes initially
indentWidth	number	20	Indentation per level (pixels)
showExpandIcons	boolean	true	Show expand/collapse toggle icons
animation	false | 'slide' | 'fade'	'slide'	Animation style for expand/collapse

Programmatic API

Method	Signature	Description
expand	(nodeId) => void	Expand a specific node
collapse	(nodeId) => void	Collapse a specific node
toggle	(nodeId) => void	Toggle a node’s expanded state
expandAll	() => void	Expand all nodes
collapseAll	() => void	Collapse all nodes
getExpandedNodes	() => Set<string>	Get currently expanded node keys

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

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.

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: unknown): boolean

Parameters

Name	Type	Description
rows	unknown

---

expand()

expand(key: string): void

Parameters

Name	Type	Description
key	string

---

collapse()

collapse(key: string): void

Parameters

Name	Type	Description
key	string

---

toggle()

toggle(key: string): void

Parameters

Name	Type	Description
key	string

---

expandAll()

expandAll(): void

---

collapseAll()

collapseAll(): void

---

isExpanded()

isExpanded(key: string): boolean

Parameters

Name	Type	Description
key	string

---

getExpandedKeys()

getExpandedKeys(): string[]

---

getFlattenedRows()

getFlattenedRows(): FlattenedTreeRow<TreeRow>[]

---

getRowByKey()

getRowByKey(key: string): TreeRow | undefined

Parameters

Name	Type	Description
key	string

---

expandToKey()

expandToKey(key: string): void

Parameters

Name	Type	Description
key	string

---