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.

TypeScript

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 { GridTreeDirective } from '@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, GridTreeDirective],
  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

With Pinned Columns

Use treeColumn to control which column displays the tree toggle when combining tree with pinned (sticky) columns. By default the toggle appears on the first visible column — set treeColumn to explicitly target a wider column like 'name'.

TREE

Tree column Which column shows the tree toggle and indentation

(first)namedepartment

Indent width (px) Indentation per nesting level

20

PINNED

Pin ID column Pin the ID column to the left

Pin Name column Pin the Name column to the left

Show source

Server-Side Data

Requires: ServerSidePlugin — see Server-Side Plugin

For large hierarchical datasets, use ServerSidePlugin to fetch top-level tree nodes in blocks as the user scrolls. TreePlugin claims the incoming data and renders the hierarchy. Children can be embedded in the response or fetched lazily via getChildRows().

TypeScript

import { queryGrid } from '@toolbox-web/grid';
import '@toolbox-web/grid/features/tree';
import '@toolbox-web/grid/features/server-side';

const grid = queryGrid('tbw-grid');
grid.gridConfig = {
  columns: [
    { field: 'name', header: 'Name' },
    { field: 'role', header: 'Role' },
  ],
  features: {
    serverSide: {
      pageSize: 50,
      dataSource: {
        async getRows(params) {
          // params: { startNode, endNode, sortModel, filterModel }
          const res = await fetch(`/api/tree?start=${params.startNode}&end=${params.endNode}`);
          const data = await res.json();
          return {
            rows: data.nodes,             // Top-level nodes with embedded children
            totalNodeCount: data.total,   // Total top-level nodes on server
          };
        },
      },
    },
    tree: { childrenField: 'children' },
  },
};

React

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

const dataSource = {
  async getRows(params) {
    const res = await fetch(`/api/tree?start=${params.startNode}&end=${params.endNode}`);
    return res.json();
  },
};

function ServerTree() {
  return (
    <DataGrid
      columns={[
        { field: 'name', header: 'Name' },
        { field: 'role', header: 'Role' },
      ]}
      serverSide={{ pageSize: 50, dataSource }}
      tree={{ childrenField: 'children' }}
    />
  );
}

Vue

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

const serverSideConfig = {
  pageSize: 50,
  dataSource: {
    async getRows(params) {
      const res = await fetch(`/api/tree?start=${params.startNode}&end=${params.endNode}`);
      return res.json();
    },
  },
};
</script>

<template>
  <TbwGrid :server-side="serverSideConfig" :tree="{ childrenField: 'children' }">
    <TbwGridColumn field="name" header="Name" />
    <TbwGridColumn field="role" header="Role" />
  </TbwGrid>
</template>

Angular

import { GridTreeDirective } from '@toolbox-web/grid-angular/features/tree';
import { GridServerSideDirective } from '@toolbox-web/grid-angular/features/server-side';
import { Component } from '@angular/core';
import { Grid } from '@toolbox-web/grid-angular';
import type { ColumnConfig } from '@toolbox-web/grid';

@Component({
  selector: 'app-server-tree',
  imports: [Grid, GridTreeDirective, GridServerSideDirective],
  template: `
    <tbw-grid
      [columns]="columns"
      [serverSide]="serverSideConfig"
      [tree]="{ childrenField: 'children' }"
      style="height: 400px; display: block;">
    </tbw-grid>
  `,
})
export class ServerTreeComponent {
  columns: ColumnConfig[] = [
    { field: 'name', header: 'Name' },
    { field: 'role', header: 'Role' },
  ];

  serverSideConfig = {
    pageSize: 50,
    dataSource: {
      async getRows(params: any) {
        const res = await fetch(`/api/tree?start=${params.startNode}&end=${params.endNode}`);
        return res.json();
      },
    },
  };
}

SERVER

Page size Top-level nodes fetched per request

20

TREE

Animation Expand/collapse animation

slidefadefalse

Default expanded Expand all nodes by default

Scroll down to load more nodes…

Show source

Data flow:

1. ServerSide fetches a block of top-level nodes → broadcasts datasource:data
2. TreePlugin claims the data and flattens it into the row model
3. Expand/collapse works locally for nodes with embedded children
4. For lazy children: TreePlugin queries datasource:fetch-children → ServerSide calls getChildRows() → broadcasts datasource:children → TreePlugin renders children

Note

Child rows are fetched as a single batch — no pagination. If a tree node has many children, limit the response server-side.

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.

Tree Column

By default, the tree toggle and indentation appear on the first visible column. Use treeColumn to target a specific column — useful when combining with pinned columns or when the first column is narrow:

features: {
  tree: {
    treeColumn: 'name',      // Show tree toggle on the 'name' column
    childrenField: 'children',
  },
  pinnedColumns: true,
}

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

Show source

tree-expand

Fired when a node is expanded or collapsed (via click, keyboard, toggle(), expandAll(), or collapseAll()):

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

See TreeExpandDetail for the full event payload type.

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

Plugin Compatibility

Incompatible Plugins

The Tree plugin cannot be used with the following plugins:

• Row Grouping — Both plugins transform the entire row model. Tree flattens nested hierarchies while Row Grouping groups flat rows with synthetic headers. Use one approach per grid.
• Pivot — Pivot replaces the entire row and column structure with aggregated pivot data. Tree hierarchy cannot coexist with pivot aggregation.

A development-mode warning is shown if incompatible plugins are loaded together.

See Also

• Master-Detail — Expand rows to show nested detail grids
• Server-Side Plugin — Lazy-load child nodes from the server