Expand All

  Getting Started

  Reference

  Features

  Row Models

  Themes new

  Components

  Examples

  Third Party

Misc

Github stars make projects look great. Please help, donate a star, it's free.
Read about ag-Grid's Partnership with webpack.
Get informed on releases and other ag-Grid news only - never spam.
Follow on Twitter

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.

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) it's 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 simple 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.