Tree Data
Use Tree Data to display data that has parent / child relationships where the parent / child relationships are
provided as part of the data. For example, a folder can contain zero or more files and other folders.
This section introduces simple ways to work with Tree Data before covering more advanced use cases.
How Tree Data is managed in ag-Grid was changed in ag-Grid v14. This page presents the new way of working with Tree Data.
The old way was part of ag-Grid free, the new way is part of ag-Grid Enterprise. The old way is deprecated but you
can still use it, but we will not be enhancing it. For documentation on the older version of the grid prior to v14
see Tree Data (Legacy).
Tree Data Mode
In order to set the grid to work with Tree Data, simply enable Tree Data mode via the Grid Options using:
gridOptions.treeData = true.
Supplying Tree Data
When providing tree data to the grid you implement the gridOptions.getDataPath(data) callback
to tell the grid the hierarchy for each row. The callback returns back a string[] with each
element specifying a level of the tree. Below follows two examples presenting the hierarchy in different ways.
// sample hierarchy, Malcolm is child or Erica
+ Erica
- Malcolm
// ############
// Example #1 - hierarchy in the data is already a string array
// ############
var rowData = [
{orgHierarchy: ['Erica'], jobTitle: "CEO", employmentType: "Permanent"},
{orgHierarchy: ['Erica', 'Malcolm'], jobTitle: "VP", employmentType: "Permanent"}
...
]
// just return the hierarchy, no conversion required
getDataPath: function(data) {
return data.orgHierarchy;
}
// ############
// Example #2 - hierarchy is a path string, needs conversion
// ############
var rowData = [
{path: "Erica", jobTitle: "CEO", employmentType: "Permanent"},
{path: "Erica/Malcolm", jobTitle: "VP", employmentType: "Permanent"}
...
]
// callback converts eg "Erica/Malcolm" to ["Erica","Malcolm"]
getDataPath: function(data) {
return data.path.split('/'); // path: "Erica/Malcolm"
}
Configuring Group Column
There are two ways to configure the Group Column:
- Auto Column Group - this is automatically selected by the grid when in Tree Data mode, however
you can override the defaults.
- Custom Column Group - you can provide your own custom column group definition which gives allows
more control over how the Group Column is displayed.
Auto Column Group
When the grid is working with Tree Data there is no need to explicitly specify a Column Group as the grid will
use the Auto Column Group. However you will
probably want to override some of the defaults as shown below:
autoGroupColumnDef: {
headerName: "My Group",
width: 300,
cellRendererParams: {
suppressCount: true
}
}
Custom Column Group
As noted above, providing your own Custom Column Group has the advantage of giving you full control over the
presentation of the Column Group, however it is not as convenient as using the default Auto Column Group.
One significant difference is that the entire dataPath array will be supplied as a value, rather
than just the current node value.
For details on how you can provide your own Custom Group Column see: Specifying Group Columns.
It is not possible to have multiple group display columns for tree data like you do for row grouping.
When doing tree data, you should only have one column for display the group.
Example - Organisational Hierarchy
The following example combines all the steps above to show a simplified organisational hierarchy:
Filler Groups
It is not necessary to include entries for each level in the path if data is not required at group levels as shown below:
// all path levels provided
var rowData = [
{filePath: ['Documents']},
{filePath: ['Documents', 'txt']},
{filePath: ['Documents', 'txt', 'notes.txt'], dateModified: "21 May 2017, 13:50", size: "14 KB"}
...
]
// only leaf level provided
var rowData = [
{filePath: ['Documents', 'txt', 'notes.txt'], dateModified: "21 May 2017, 13:50", size: "14 KB"}
...
]
The second variation above leaves out row data entries for 'Documents' and 'txt' nodes, in this case the grid
will create Filler Groups for these.
This following example includes the column 'Group Type' to highlight which nodes are 'provided' in the row data and
which are generated by the grid as a 'filler' group:
As Filler Groups are generated by the grid they will not contain a data property on the RowNode.
This could be a limitation if you wanted to provide an 'id' for each group even when there is no data displayed at group levels.
Tree Data Aggregation
When using Tree Data, columns defined with an aggregation function will always perform aggregations on the group nodes.
This means any supplied group data will be ignored in favour of the aggregated values.
However if there are no child nodes to aggregate it will default to the provided value in the row data.
The File Browser example below demonstrates aggregation
on the 'size' column.
Also you can refer to the section on Aggregation more details.
Tree Data Filtering
Other than the Set Filter, filtering works the same way
with Tree Data.
When using Tree Data the Set Filter will contain a list all unique values across each level of the group hierarchy.
Also note that as filtering is performed across all group levels, a group will be included if:
- a) it has any children, or
- b) its data passes the filter
The File Browser example below demonstrates the Set Filter works with Tree Data.
Example - File Browser
The following example presents a more complex example which includes Aggregation and Filtering:
- 'Add New Group' Button - will add a new group under Music.
- 'Move Selected to stuff' Button - will move any non parent groups into the 'stuff' folder.
- 'Remove Selected' Button - will remove selected group along with children.
- 'Files' Filter - you can filter group and leaf names across the entire file tree.
- 'Size' Aggregation - as you move selected items into 'stuff' you'll notice updated folder sizes.
Pivot and Row Grouping with Tree Data
It is not possible to do pivot or row grouping while using tree data. This means all the functions
related to pivot (eg colDef.pivot, or pivot in the tool panel) and row grouping (eg colDef.rowGroup, or
row group in the tool panel) will be disabled.
Child Counts
If you are showing child counts for the groups, then the child count is a count of all children and grand children.
This is different to Row Grouping where only leaf levels are counted,
in tree data, all group children are also counted.
Selection
To enable selection set gridOptions.rowSelection to 'single' or 'multiple'
as normal. However there are some restrictions to be aware of.
Selecting Groups and Children
The property groupSelectsChildren does not work with tree data. This is because
groups in tree data are rows passed by the application that may or may not have children - a
group is simply a normal row that has another row as a child. Given groups and leaf nodes
are logically identical, it is not possible to treat them differently in selection.
If you want to achieve something similar to groupSelectsChildren then you should
listen on the selection events and do the selection yourself in your application. You will come
across edge cases where only your application will understand what the best selection outcome is.
Checkbox vs Click Selection
Click selection is supported with tree data. However when you are displaying tree data, clicking
rows for selection is confusing as mouse clicks are also used for expanding / contracting rows.
For this reason we recommend not using click selecting and preferring checkbox selection instead.
var gridOptions = {
// don't have click select rows
suppressRowClickSelection: true,
// have checkbox on the group column
autoGroupColumnDef: {
cellRendererParams: {
checkbox: true,
}
}
...
}
Group Selection
Filler groups do not keep their selection state should the filler group be moved.
For example if you have groups A->B->C, where C is the only row provided (so the grid
creates groups A and B for you), and then you change the patch to D->B->C, group B
will not keep it's selection.
If keeping selection of groups is a priority, then arrange your data so that the
grid does not need to create any filler groups.