- Data Grid docs
- Working with records
Tree data
Show records as a tree from a parent field or an outline level, open and close branches, and roll numbers up to each parent; locally or from your server.
Some records belong under other records: people under their manager, tasks under their project, accounts under their group. A tree shows them that way, each record indented under its parent with an arrow to open or close its branch, while search, filters, sorting and editing keep working on the records themselves.
Open the tree example: a company of 240 people, salaries rolled up to each manager
In the grid
- Group in the toolbar has Show as tree…. Pick the Key field (each record's own key) and the Parent field (the key of the record it belongs under), or a Level field that holds an outline level per record (0 for the top, 1 under it, and so on). Remove tree shows the list again.
- A chip above the grid shows that the records are a tree; removing it removes the tree.
- A parent's arrow opens or closes its branch.
- Search and filters keep the ancestors of every matching record, so a match deep in the tree still shows where it belongs.
- Sorting orders the records within each parent: siblings follow the sort, children stay under their parent.
From code
| State or method | Does |
|---|---|
tree: { parent, key, rollups? } | Puts each record under the record whose key field holds its parent value |
tree: { level, rollups? } | Reads an outline level per record from the level field; each record goes under the nearest record above it with a lower level |
treeCollapsed: [id, …] | The IDs of the parents shown collapsed |
setTree(tree), setTree(null) | Shows the records as a tree, or as a list again |
expandTreeNode(id), collapseTreeNode(id) | Opens or closes one parent's branch |
expandAll(), collapseAll() | Opens or closes every branch, as they do every group |
Give key with parent; it can be left out only for a table that has a key field of its own, such as a server table's key in tableQueryService.
rollups lists fields whose value a parent shows as what its descendants add up to: { field, agg }, with agg one of sum (the default), average, min, max and count. In the tree example, each manager's Salary is the sum of the salaries of everyone under them.
A tree replaces the groups: setTree and Show as tree… clear groups, and the context menu offers no Group by while the tree is shown. Each change fires stateChange with tree or treeCollapsed among the keys that changed.
JavaScript
import { mountTable } from '@8sheets/data-grid';
const grid = await mountTable(document.querySelector('#team'), {
title: 'Company',
fields: [
{ name: 'Id', type: 'number', format: '0' },
{ name: 'Manager', type: 'number', format: '0' },
{ name: 'Name', type: 'string' },
{ name: 'Office', type: 'string', options: ['Warsaw', 'Berlin', 'Paris'] },
{ name: 'Salary', type: 'number', format: '#,##0' },
],
data: people, // { Id: 7, Manager: 2, Name: 'Ada Novak', Office: 'Paris', Salary: 9200 }, …
});
await grid.setTree({ parent: 'Manager', key: 'Id', rollups: [{ field: 'Salary', agg: 'sum' }] });
await grid.setColumn('Id', { hidden: true });
await grid.setColumn('Manager', { hidden: true });
await grid.collapseAll();
await grid.expandTreeNode(0); // the first record, the head of the company, stays openReact
import { useMemo } from 'react';
import { DataGrid } from '@8sheets/data-grid-react';
export function Company({ people, fields }) {
const options = useMemo(() => ({ title: 'Company', fields, data: people }), [people, fields]);
return (
<div style={{ height: 600 }}>
<DataGrid
options={options}
onReady={(grid) => grid.setTree({ parent: 'Manager', key: 'Id', rollups: [{ field: 'Salary' }] })}
/>
</div>
);
}Vue
<script setup>
import { computed } from 'vue';
import { DataGrid } from '@8sheets/data-grid-vue';
const props = defineProps({ people: Array, fields: Array });
const options = computed(() => ({ title: 'Company', fields: props.fields, data: props.people }));
const onReady = (grid) => grid.setTree({ parent: 'Manager', key: 'Id', rollups: [{ field: 'Salary' }] });
</script>
<template>
<div style="height: 600px"><DataGrid :options="options" @ready="onReady" /></div>
</template>Angular
import { Component, Input } from '@angular/core';
import { DataGridComponent, DataGridOptions, MountedDataGrid } from '@8sheets/data-grid-angular';
@Component({
selector: 'app-company',
imports: [DataGridComponent],
template: `<eight-data-grid [options]="options" (ready)="onReady($event)" style="height: 600px" />`,
})
export class Company {
@Input() options: DataGridOptions = {};
onReady(grid: MountedDataGrid) {
grid.setTree({ parent: 'Manager', key: 'Id', rollups: [{ field: 'Salary' }] });
}
}A tree is part of the view state, so setState({ tree }) and saved views carry it too:
await grid.updateState({ tree: { level: 'Outline' }, treeCollapsed: [] });
A record whose parent value matches no record shows at the top level. Records caught in a parent cycle also show at the top level rather than disappear.
With a server source
The grid sends tree and treeCollapsed in the view state; treeCollapsed names records by their IDs, as your rows give them. Each record row of the answer then carries its level, whether it hasChildren, and whether it is collapsed, and the page may list the collapsed parents in treeCollapsed. The server keeps the ancestors of matching records and computes the rollups. tableQueryService in the source download does all of this.
{
"offset": 0,
"columns": ["Name", "Office", "Salary"],
"rows": [
{ "id": 1, "values": ["Ada Novak", "Warsaw", "412,500"], "level": 0, "hasChildren": true, "collapsed": false },
{ "id": 2, "values": ["Bo Moreau", "Berlin", "98,000"], "level": 1, "hasChildren": true, "collapsed": true }
],
"summary": ""
}
Limits
- A tree and groups don't combine: a tree replaces the groups.
- Records can't be moved by dragging while they are shown as a tree; see Pinned rows, moving and numbers.
- The Show as tree dialog sets the structure; rollups are set from code, through
setTreeor the state. - A rolled-up value stands in for the parent's own value on screen; it isn't stored in the record.