Grid Group By

igxGrid supports column grouping that allows for visualizing data records in hierarchical groups according to the column group values. Groups can be expanded or collapsed and the order of grouping may be changed through the UI or API.

Demo

Initial Grouping State

It is possible to set the initial grouping of the grid by an array of expressions to the groupingExpressions property of the grid.

public ngOnInit() {
    grid.groupingExpressions = [
        { fieldName: 'ProductName', dir: SortingDirection.Desc },
        { fieldName: 'Released', dir: SortingDirection.Desc }
    ];
}

Grouping expressions implement the ISortingExpression interface.

Group By API

Grouping is available through the UI and through a robust API exposed by the grid component. Developers can allow end-users to group the grid data by certain columns, by setting each column's groupable property to true.

<igx-grid [data]="data">
    <igx-column *ngFor="let c of columns" [field]="c.field" [groupable]="true">
    </igx-column>
</igx-grid>
public ngOnInit() {
    grid.columns.forEach((column) => {
        column.groupable = true;
    });
}

During runtime the expressions are gettable and settable from the groupingExpressions property. If you need to just add or change an existing expression you may also use the groupBy method with either a single or an array of ISortingExpression.

grid.groupBy({ fieldName: 'ProductName', dir: SortingDirection.Desc, ignoreCase: true });

Grouping works in conjunction with sorting and grouping expressions are applied as sorting ones even though columns may be sorted without being grouped. You will always find the grouping expressions in the sortingExpressions property, sorted in a way that grouped columns' expressions are always first. The sorting API will affect grouping if it changes the expression for a column that is grouped. Removing a grouping expression (ungrouping a column) also unsorts it.

In addition to grouping expressions you can also control the expansion states for group rows. They are stored in a separate property of the igxGrid component groupingExpansionState. A group row is uniquely identified based on the field name it is created for and the value it represents for each level of grouping. This means that the signature of an expansion state interface is the following:

export interface IGroupByKey {
    fieldName: string;
    value: any;
}

export interface IGroupByExpandState {
    hierarchy: Array<IGroupByKey>;
    expanded: boolean;
}

As with groupingExpressions, setting a list of IGroupByExpandState directly to the groupingExpansionState will change the expansion accordingly. Additionally igxGrid exposes a method that toggles a group by the group record instance.

    const groupRow = this.grid.groupsRecords.find(r => r.value === "France");
    grid.toggleGroup(groupRow);

Groups can be created expanded (default) or collapsed and the expansion states would generally only contain the state opposite to the default behavior. You can control whether groups should be created expanded or not through the groupsExpanded property.

Group Row Templates

The group row without its expand/collapse UI is fully templatable. By default it renders a grouping icon and displays the field name and value it represents. The grouping record template is rendered against has the following signature:

export interface IGroupByRecord {
    expression: ISortingExpression;
    level: number;
    records: GroupedRecords;
    value: any;
    groupParent: IGroupByRecord;
    groups?: IGroupByRecord[];
}

As an example, the following template would make the group rows summary more verbose:

<ng-template igxGroupByRow let-groupRow>
    <span>Total items with value: {{ groupRow.value }} are {{ groupRow.records.length }}</span>
</ng-template>

Keyboard Navigation

The grouping UI supports the following keyboard interactions:

  • For group rows (focus should be on the row or the expand/collapse cell)

    • ALT + RIGHT - Expands the group
    • ALT + LEFT - Collapses the group
  • For group igxChip components in the group by area (focus should be on the chip)

    • SHIFT + LEFT - moves the focused chip left, changing the grouping order, if possible
    • SHIFT + RIGHT - moves the focused chip right, changing the grouping order, if possible
    • SPACE - changes the sorting direction
    • DELETE - ungroups the field
    • The seperate elements of the chip are also focusable and can be interacted with using the ENTER key.

Known Limitations

Limitation Description
Maximum amount of grouped columns is 10. If more than 10 columns are grouped an error is thrown.

API

Additional Resources

Our community is active and always welcoming to new ideas.

View page on GitHub