Grouping

DataGrid provides you with the capability to group grid records by values of a single or multiple columns. When grouping is applied, records with identical values in the same column or several columns are combined into one or several corresponding groups. Visually, groups are separated one from another by a group row containing a grouping value. This topic gathers information about settings that define user-specified grouping and methods that can be used to apply grouping in code.

To group records, the user right-clicks a column header. This action invokes the context menu suggesting that the user selects a required item from it. Alternatively, the user can group data by dragging and dropping column headers onto/from the group panel. Try both these grouping approaches in action in the DataGrid below.

Groups in a grid are always sorted even if sorting was not applied to the column before it has been used for grouping. By default, groups are sorted in ascending order. To change this, a user must click the header of the grouping column.

NOTE: When moving a column back from the group panel, its resulting location depends on the allowColumnReordering option. If this option is true, the column will be placed exactly where its header is dropped. If false, the column will have a location according to the order of columns in the columns array.

Grouping in UI

Grouping in the UI can be performed using the context menu. To enable this capability, assign true to the grouping | contextMenuEnabled option.

JavaScript
var dataGridOptions = {
    // ...
    grouping: { contextMenuEnabled: true }
};

To allow grouping with the group panel as well, make the group panel visible using the groupPanel | visible option.

JavaScript
var dataGridOptions = {
    // ...
    groupPanel: { visible: true }
};
See Also

The foregoing options enable grouping for all grid columns. In case you need to disable grouping for a particular column, set its allowGrouping option to false.

JavaScript
var dataGridOptions = {
    // ...
    columns: [{
        // ...
        allowGrouping: false
    }]
};

View Demo

Grouping in Code

If required, you can apply grouping in code. For this purpose, assign an integer number to the groupIndex option of the required column using the columnOption method. To ungroup records, assign undefined to this option using the same method. To clear grouping settings of all columns, call the clearGrouping() method as shown in the code snippet below.

JavaScript
dataGridInstance.clearGrouping();

Calculating the Group Index

A group index is an integer number greater or equal to 0 that indicates the grouping order. The group index is used when specifying an initial grouping order or expanding/collapsing groups in code. Columns that are not used in grouping have the undefined group index. The following image illustrates how to calculate the group index.

DevExtreme DataGrid GroupIndexes

Expanding and Collapsing Groups

Groups can be either expanded or collapsed. When expanded, a group is represented by a group row and data rows matching the grouping value. When collapsed, a group is represented by a group row only.

DevExtreme DataGrid Groups

By default, to expand/collapse a group, the user clicks its expand/collapse button. On small-screen devices, this approach may impair the user experience. As an alternative, consider expanding/collapsing a group by a click on the group row. To specify the preferable mode, use the grouping | expandMode option.

JavaScript
var dataGridOptions = {
    // ...
    grouping: {
        // ...
        expandMode: 'buttonClick' // or 'rowClick'
    }
};

You can entirely disallow the user to collapse groups. For this purpose, set the grouping | allowCollapsing option to false.

JavaScript
var dataGridOptions = {
    // ...
    grouping: {
        // ...
        allowCollapsing: false // disallows group collapsing
    }
  };

Groups in a grid may appear expanded or collapsed initially. To specify this for all groups, use the grouping | autoExpandAll option. If you need to specify this setting for an individual column, use its autoExpandGroup option.

JavaScript
var dataGridOptions = {
    // ...
    grouping: {
        // ...
        autoExpandAll: true // makes all groups appear expanded
    },
    columns: [{
        // ...
        autoExpandGroup: false // groups of this column appear collapsed
    }]
  };

To expand/collapse a group in code, call the expandAll(groupIndex) or collapseAll(groupIndex) methods. To discover how to calculate the group index, which is passed to these methods, refer to the Calculating the Group Index subtopic. Calling these methods without the argument expands/collapses all groups.

You can also perform custom actions before or after expanding/collapsing groups. For this purpose, use the rowExpanding, rowExpanded, rowCollapsing and rowCollapsed events.

Setting Initial Grouping

Grouping can be applied not only at runtime, but also at design time. To do this, assign an integer value to the groupIndex option of those columns that must be used in grouping. Note that grouping order is based on those values. If grouping in the UI is prohibited, the user will not be able to change the initially set grouping.

JavaScript
var dataGridOptions = {
    // ...
    columns: [{
        // ...
        groupIndex: 0
    }, {
        // ...
        groupIndex: 1
    }]
};

For information about calculating the group index, see the Calculating the Group Index subtopic.