Angular Data GridTree Data
angular logo
Enterprise

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 as well as other folders.

This section introduces simple ways to work with Tree Data, before covering more advanced use cases.

Tree Data Mode

In order to set the grid to work with Tree Data, simply enable Tree Data mode via the Grid Options using:

<ag-grid-angular
    [treeData]="treeData"
    /* other grid options ... */>
</ag-grid-angular>

this.treeData = true;

Supplying Tree Data

When providing tree data to the grid, you will need to implement the gridOptions.getDataPath(data) callback to tell the grid the hierarchy for each row. The callback must return a string[] representing the route, with each element specifying a level of the tree. Below are two examples presenting the hierarchy in different ways.

// sample hierarchy, Malcolm is child of Erica
// + Erica
//   - Malcolm

// ############
// Example #1 - hierarchy in the data is already a string array
// ############
const rowData = [
    { orgHierarchy: ['Erica'], jobTitle: "CEO", employmentType: "Permanent" },
    { orgHierarchy: ['Erica', 'Malcolm'], jobTitle: "VP", employmentType: "Permanent" }
    ...
]
// just return the hierarchy, no conversion required
getDataPath: data => {
    return data.orgHierarchy;
}

// ############
// Example #2 - hierarchy is a path string, needs conversion
// ############
const rowData = [
    { path: "Erica", jobTitle: "CEO", employmentType: "Permanent" },
    { path: "Erica/Malcolm", jobTitle: "VP", employmentType: "Permanent" }
    ...
]
// callback converts "Erica/Malcolm" to ["Erica","Malcolm"]
getDataPath: 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 default.

  • 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 Group Column as the grid will use the Auto Group Column. However, you will probably want to override some defaults as shown below:

<ag-grid-angular
    [autoGroupColumnDef]="autoGroupColumnDef"
    /* other grid options ... */>
</ag-grid-angular>

this.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 need to be supplied as a value, rather than just the current node value.

For more details see Custom Group Columns

It is not possible to have multiple group display columns for tree data like you do for row grouping. When using tree data, you should only have one column to 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 each group level. Compare the two code snippets below:

// all path levels provided
const rowData = [
    { filePath: ['Documents'] },
    { filePath: ['Documents', 'txt'] },
    { filePath: ['Documents', 'txt', 'notes.txt'], dateModified: "21 May 2017, 13:50", size: "14 KB" }
    ...
]

// only leaf level provided
const rowData = [
    { filePath: ['Documents', 'txt', 'notes.txt'], dateModified: "21 May 2017, 13:50", size: "14 KB" }
    ...
]

The second variation 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 or if you need to filter/sort the Filler Groups. In order to have filtering/sorting available on Filler Groups, you will need to provide all nodes as real nodes from your dataset, instead of using Filler Groups.

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, the provided value in the row data will be displayed.

The File Browser example below demonstrates aggregation on the 'size' column. Note how the size provided in the data for 'Documents' is ignored and the aggregated value is used instead, whereas 'temp.txt' displays the provided size from the data as it has no children.

See Aggregation for more details about group aggregation.

File Browser Example

The following example is a more complex example that includes Aggregation:

  • 'Add New Group' Button - will add a new item in a new group under Music.
  • 'Move Selected to stuff' Button - will move any selected item and its children into the 'stuff' folder.
  • 'Remove Selected' Button - will remove selected item along with its children.
  • 'Size' Aggregation - as you move selected items into 'stuff' you'll notice updated folder sizes.

Tree Data Filtering

As Tree Data has parent / child relationships, by default all child nodes will be included when a parent passes a filter. Filtering is additionally performed across all group levels. Therefore a group will be included if:

  1. it has any children that pass the filter, or
  2. it has a parent that passes the filter, or
  3. its own data passes the filter

This can be seen in the File Browser example above, where the 'Files' column filter will filter group and leaf names across the entire file tree.

To disable Tree Data filtering and use regular filtering instead (which only shows groups where leaf children pass the filter), enable the following Grid Options property:

<ag-grid-angular
    [excludeChildrenWhenTreeDataFiltering]="excludeChildrenWhenTreeDataFiltering"
    /* other grid options ... */>
</ag-grid-angular>

this.excludeChildrenWhenTreeDataFiltering = true;

Please note that Tree Data filtering behaves slightly differently to Filtering Group Aggregations.

Filtering Aggregated Parent Rows

The default behaviour of a group filter is to ignore aggregated group values that pass the filter, but this can be changed by enabling groupAggFiltering.

The default behaviour of a Tree Data filter is to match aggregated group values as well, and setting the groupAggFiltering property to true or false will not change this. The one exception is that the Set Filter will not match a value in a parent row when groupAggFiltering is false. You can also change this behaviour by using Custom Group Aggregation Filtering because passing a function to the groupAggFiltering property will work the same as without Tree Data filtering.

Aggregated Values Based on Pre-Filtered Data

The default behaviour of both Tree Data and group filters is to calculate aggregated values from the filtered results only. This can be changed by setting suppressAggFilteredOnly = true.

This behaviour can also be achieved in the Tree Data filter by setting groupAggFiltering = true.

As mentioned, if Tree Data filtering is disabled by setting excludeChildrenWhenTreeDataFiltering = true, then groupAggFiltering will work as normal.

The following example demonstrates aggregated values based on pre-filtered data by setting groupAggFiltering = true.

  • Using the Size column apply a filter for the value 24.6. Note that all results are displayed.
  • Using the Size column apply a filter for the value 2.4. Note that the 'cv.pdf' row and its parents are displayed. The value in the Size column for the 'Documents' parent row is 24.6 MB (the pre-filtered value).

Set Filter

When used with Tree Data, the Set Filter will contain a list of all unique values across each level of the group hierarchy. The File Browser example above demonstrates how the Set Filter works with Tree Data.

It is also possible to display the Set Filter List as a Set Filter Tree List, which replicates the Tree Data structure. This can be seen in the Tree List example below.

The Tree List also works with complex objects, which is demonstrated in the Tree List Complex Objects Example.

The example below demonstrates using the Set Filter Tree List with Tree Data. Note the following:

  1. The Employee group column has the Set Filter Tree List enabled via filterParams.treeList = true. A Key Creator is specified to convert the path into a string.
  2. The Filter List displayed for the Employee column matches the format of the Tree Data structure.
  3. The Date column has filterParams.treeList = true and is grouped by year -> month -> day.

Pivot and Row Grouping with Tree Data

It is not possible to do pivot or row grouping while using tree data. This means that 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 grandchildren. 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.

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 selection and using checkbox selection instead.

<ag-grid-angular
    [suppressRowClickSelection]="suppressRowClickSelection"
    [autoGroupColumnDef]="autoGroupColumnDef"
    /* other grid options ... */>
</ag-grid-angular>

// don't have click select rows
this.suppressRowClickSelection = true;

// have checkbox on the group column
this.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 path to D->B->C, group B will not keep its 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.

Example: Selecting Groups and Children

Below is an example demonstrating the property groupSelectsChildren used with tree data.

In the example below, note the following:

  • Selecting all child rows will select the parent
  • Selecting only some children will mark the parents as partially selected
  • Selecting a row, and then selecting another while holding the shift key will select all rows between the two rows
  • Selecting a parent will also select all of its children

Next Up

Continue to the next section to learn about Pivoting.