Grid Group By

A Group by behavior in an Angular Material table or UI grid creates grouped data rows based on the column values. The Group By in igxGrid allows for visualizing the groups in a hierarchical structure. The grouped data rows 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 define initial grouping of the grid by assigning 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 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>

Group By with Paging

Group rows participate in the paging process along with data rows. They count towards the page size for each page. Collapsed rows are not included in the paging process. Any expand or collapse operation forces Paging to recalculate the page count and adjust the page index if necessary. Groups that span multiple pages are split between them. The group row is visible only on the page it starts on and is not repeated on subsequent pages. Summary information for group rows is calculated based on the whole group and is unaffected by Paging.

Demo

Group By with Summaries

Integration between Group By and Summaries is described in the Summaries topic.

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 References

Additional Resources

Our community is active and always welcoming to new ideas.