Tree Plugin

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

Installation

import '@toolbox-web/grid/features/tree';

Basic Usage

Just point the feature at the field containing child items (defaults to children) and the grid handles all the expand/collapse behavior, indentation, and icons automatically.

Vanilla JS

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

const grid = queryGrid('tbw-grid');
grid.gridConfig = {
  columns: [
    { field: 'name', header: 'Name' },
    { field: 'type', header: 'Type' },
    { field: 'size', header: 'Size' }
  ],
  features: {
    tree: {
      childrenField: 'children',
      indentWidth: 24,
    },
  },
};

grid.rows = [
  {
    id: 1,
    name: 'Documents',
    type: 'folder',
    children: [
      { id: 2, name: 'Work', type: 'folder', children: [
        { id: 3, name: 'Report.docx', type: 'file', size: '24 KB' }
      ]},
      { id: 4, name: 'Personal', type: 'folder', children: [] }
    ]
  },
];

React

import '@toolbox-web/grid-react/features/tree';
import { DataGrid } from '@toolbox-web/grid-react';

function FileExplorer({ files }) {
  return (
    <DataGrid
      rows={files}
      columns={[
        { field: 'name', header: 'Name' },
        { field: 'type', header: 'Type' },
        { field: 'size', header: 'Size' }
      ]}
      tree={{ childrenField: 'children', indentWidth: 24 }}
    />
  );
}

Vue

<script setup>
import '@toolbox-web/grid-vue/features/tree';
import { TbwGrid, TbwGridColumn } from '@toolbox-web/grid-vue';

const files = [
  {
    id: 1,
    name: 'Documents',
    type: 'folder',
    children: [
      { id: 2, name: 'Work', type: 'folder', children: [{ id: 3, name: 'Report.docx', type: 'file', size: '24 KB' }] },
      { id: 4, name: 'Personal', type: 'folder', children: [] },
    ],
  },
];
</script>

<template>
  <TbwGrid :rows="files" :tree="{ childrenField: 'children', indentWidth: 24 }">
    <TbwGridColumn field="name" header="Name" />
    <TbwGridColumn field="type" header="Type" />
    <TbwGridColumn field="size" header="Size" />
  </TbwGrid>
</template>

Angular

// Feature import - enables the [tree] input
import '@toolbox-web/grid-angular/features/tree';

import { Component } from '@angular/core';
import { Grid } from '@toolbox-web/grid-angular';
import type { ColumnConfig } from '@toolbox-web/grid';

@Component({
  selector: 'app-file-explorer',
  imports: [Grid],
  template: `
    <tbw-grid
      [rows]="files"
      [columns]="columns"
      [tree]="{ childrenField: 'children', indentWidth: 24 }"
      style="height: 400px; display: block;">
    </tbw-grid>
  `,
})
export class FileExplorerComponent {
  files = [/* hierarchical data */];

  columns: ColumnConfig[] = [
    { field: 'name', header: 'Name' },
    { field: 'type', header: 'Type' },
    { field: 'size', header: 'Size' }
  ];
}

Demo

Toggle the controls to explore animation, indentation, and expand behavior.

TREE

Animation Expand/collapse animation

slidefadefalse

Default expanded Expand all nodes by default

Indent width (px) Indentation per nesting level

20

Show expand icons Show expand/collapse toggle icons

Show source

Configuration Options

See TreeConfig for the full list of options and defaults.

Animation Options

The animation option controls how child nodes appear/disappear:

// Slide animation (default)
features: { tree: { animation: 'slide', ... } }

// Fade animation
features: { tree: { animation: 'fade', ... } }

// No animation
features: { tree: { animation: false, ... } }

Note

Animation respects the grid-level animation.mode setting.

Programmatic API

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

plugin.expand(key);              // Expand a node by key
plugin.collapse(key);            // Collapse a node by key
plugin.toggle(key);              // Toggle a node's expanded state
plugin.expandAll();              // Expand all nodes
plugin.collapseAll();            // Collapse all nodes
plugin.expandToKey(key);         // Expand all ancestors to reveal a node
const keys = plugin.getExpandedKeys();   // Get currently expanded node keys
const expanded = plugin.isExpanded(key); // Check if a node is expanded
const rows = plugin.getFlattenedRows();  // Get flattened tree rows with metadata
const row = plugin.getRowByKey(key);     // Find a row by its key

Events

Event Log: Clear

tree-expand

Fired when a node is expanded or collapsed (via click or keyboard):

grid.on('tree-expand', ({ key, row, expanded, depth }) => {
  console.log(`${expanded ? 'Expanded' : 'Collapsed'} node ${key} at depth ${depth}`);
});

See TreeExpandDetail for the full event payload type.

tree-state-change

Fired when the overall expansion state changes (via toggle(), expandAll(), or collapseAll()):

grid.on('tree-state-change', ({ expandedKeys }) => {
  console.log(`${expandedKeys.length} nodes expanded`);
});

Styling

The tree plugin supports CSS custom properties for theming. Override these on tbw-grid or a parent container:

CSS Custom Properties

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

Note

--tbw-tree-indent-width defaults to --tbw-tree-toggle-size to ensure leaf nodes align with parent nodes. If you override indent width, ensure it’s at least as wide as the toggle icon.

Example

tbw-grid {
  /* Custom tree styling */
  --tbw-tree-toggle-size: 1.5em; /* Larger toggle icons */
  --tbw-tree-indent-width: 1.75em; /* Slightly wider indent */
  --tbw-tree-accent: #10b981;
  --tbw-animation-duration: 150ms;
}

CSS Classes

The tree plugin uses these class names:

Class	Element
.tree-cell-wrapper	Cell content wrapper with indentation
.tree-expander	Expander cell container
.tree-toggle	Expand/collapse icon
.tree-spacer	Indent spacer element
.tbw-tree-slide-in	Child row slide animation
.tbw-tree-fade-in	Child row fade animation

See Also

• Row Grouping — Group rows by field values
• Master-Detail — Expandable detail panels
• Pivot — Pivot table with row grouping