Framework:Javascript Data GridReact Data GridAngular Data GridVue Data Grid

React Data Grid: Set Filter - Tree List

This section describes the behaviour of the Set Filter Tree List and shows how it can be configured.

The Tree List allows the user to display the values in the Filter List grouped in a tree structure.

Filter Tree List

Enabling Tree Lists

Tree List is enabled by setting filterParams.treeList = true. There are four different ways the tree structure can be created:

  • The column values are of type Date, in which case the tree will be year -> month -> day.
  • Tree Data mode is enabled and the column is a group column. The Filter List will match the tree structure. A Key Creator must be supplied to convert the array of keys.
  • Grouping is enabled and the column is the group column. The Filter List will match the group structure. A Key Creator must be supplied to convert the array of keys.
  • A filterParams.treeListPathGetter is provided to get a custom tree path for the column values.
keyCreator
Function
Function to return a string key for a value. This is required when the filter values are complex objects, or when treeList = true and the column is a group column with Tree Data or Grouping enabled. If not provided, the Column Definition Key Creator is used.
keyCreator = (
    params: KeyCreatorParams<TData>
) => string;

interface KeyCreatorParams<TData = any, TValue = any> {
  // Value for the cell. 
  value: TValue;
  // Row node for the given row 
  node: IRowNode<TData> | null;
  // Data associated with the node 
  data: TData;
  // Column for this callback 
  column: Column;
  // ColDef provided for this column 
  colDef: ColDef<TData>;
  // The grid api. 
  api: GridApi<TData>;
  // The column api. 
  columnApi: ColumnApi;
  // Application context as set on `gridOptions.context`. 
  context: any;
}
treeListPathGetter
Function
Requires treeList = true. If provided, this gets the tree path to display in the Set Filter List based on the column values.
treeListPathGetter = (value: V | null) => string[] | null;
const columnDefs = [
    {
        field: 'date',
        filter: 'agSetColumnFilter',
        filterParams: {
            treeList: true,
        }
    }
];
const autoGroupColumnDef = {
    field: 'athlete',
    filter: 'agSetColumnFilter',
    filterParams: {
        treeList: true,
        keyCreator: params => params.value.join('#')
    },
};

<AgGridReact columnDefs={columnDefs} autoGroupColumnDef={autoGroupColumnDef}></AgGridReact>

The following example demonstrates enabling different types of Tree List in the Set Filter. Note the following:

  1. The Group, Date and Gold columns all have filterParams.treeList = true.
  2. The Group column Filter List matches the format of the Row Grouping. A Key Creator is specified to convert the path into a string.
  3. The Date column is grouped by year -> month -> day.
  4. The Gold column has filterParams.treeListPathGetter provided which groups the values into a tree of >2 and <=2.

Sorting Tree Lists

Sorting values for Tree Lists is similar to Sorting Filter Lists, with the exception that if the column values are of type Date, they will instead be sorted based on the raw date values.

A Comparator can be used to change the sort order of Tree Lists just like with Sorting Filter Lists, with the same conditions applying. For Tree Lists, the Comparator is applied to the child values, sorting the entire tree in one pass rather than for each level. The Comparator will be provided the following:

  • The column value for Date objects and custom tree paths.
  • The tree path (string[] or null) for Tree Data and Grouping.

The following example demonstrates changing the sorting of the Tree List. Note the following:

  1. Tree Data is turned on via treeData = true.
  2. The Employee column has filterParams.treeList = true and the Filter List matches the format of the Tree Data. A Key Creator is specified to convert the path into a string.
  3. The Employee column has a filterParams.comparator supplied which displays the Filter List in reverse alphabetical order.
  4. The Date column has filterParams.treeList = true. It also has a filterParams.comparator supplied which displays the Filter List in reverse date order.

Formatting Values

The values can be formatted in the Filter List via filterParams.treeListFormatter. This allows a different format to be used for each level of the tree.

treeListFormatter
Function
Requires treeList = true. If specified, this formats the tree values before they are displayed in the Filter List. level refers to the level of the tree (starting at 0).
treeListFormatter = (
    pathKey: string | null,
    level: number
) => string;
const columnDefs = [
    {
        field: 'date',
        filter: 'agSetColumnFilter',
        filterParams: {
            treeList: true,
            treeListFormatter: (pathKey, level) => {
                if (level === 0 && pathKey) {
                    return `Year ${pathKey}`;
                }
                return pathKey;
            }
        }
    }
];

<AgGridReact columnDefs={columnDefs}></AgGridReact>

If a formatter is provided, it will also need to handle Missing Values, which will have a pathKey of null. Without a formatter, these are displayed as (Blanks).

filterParams.valueFormatter is not used in the Filter List when filterParams.treeList = true. However, it is still used to format the values displayed in the Floating Filter. The value provided to the Value Formatter is the original value, e.g. a Date object for dates, the child value for Tree Data or Grouping, or the column value for a custom tree path.

The following example demonstrates formatting the Tree List. Note the following:

  1. The Group column has filterParams.treeList = true.
  2. The Group column has a filterParams.treeListFormatter provided which formats the country values in the Filter List to add a two letter country code. Missing values are formatted as (Blanks).
  3. The Date column has filterParams.treeList = true.
  4. The Date column has a filterParams.treeListFormatter provided which formats the numerical month value to display as the name of the month. Missing values are formatted as (Blanks).
  5. When a date is filtered in the Date column , filterParams.valueFormatter is used to format the value displayed in the Floating Filter.

Mini Filter Behaviour

When searching in the Mini Filter, all children will be included when a parent matches the search value. A parent will be included if it has any children that match the search value, or it matches itself.

Filter Value Tooltips

When using Tree List with a Custom Tooltip Component, the tooltip params will be of type ISetFilterTreeListTooltipParams which extends the Custom Tooltip params to include the level of the item within the tree.

Additional property available on ISetFilterTreeListTooltipParams:

level
number
Level of the tree (starting at 0).

Next Up

Continue to the next section: Mini Filter.