Data Grid - Row grouping

Group your rows according to some column values.

For when you need to group rows based on repeated column values, and/or custom functions. In the following example, movies are grouped based on their production company:

Grouping criteria

Initialize the row grouping

The easiest way to get started with the feature is to provide its model to the initialState prop:

<DataGridPremium
  initialState={{
    rowGrouping: {
      model: ['company', 'director'],
    },
  }}
/>

The basic parameters are the columns you want to check for repeating values. This example groups all the movies matching the same company name, followed by a second group matching the director's name.

Controlled row grouping

If you need to control the state of the criteria used for grouping, use the rowGroupingModel prop. You can use the onRowGroupingModelChange prop to listen to changes to the grouping criteria and update the prop accordingly.

Grouping columns

Single grouping column

By default, the data grid will display a single column holding all grouping columns. If you have multiple grouping criteria, this column name will be set to "Group."

Multiple grouping columns

To display a column for each grouping criterion, set the rowGroupingColumnMode prop to multiple.

Custom grouping column

To customize the rendering of the grouping column, use the groupingColDef prop. You can override the headerName or any property of the GridColDef interface, except the field, the type, and the properties related to inline edition.

By default, when using the object format, the properties will be applied to all Grouping columns. This means that if you have rowGroupingColumnMode set to multiple, all the columns will share the same groupingColDef properties.

If you wish to override properties of specific grouping columns or to apply different overrides based on the current grouping criteria, you can pass a callback function to groupingColDef, instead of an object with its config. The callback is called for each grouping column, and it receives the respective column's "fields" as parameter.

Group by company

Group by company and director

Grouping rows with custom cell renderer

By default, when rows are grouped by a column with a custom cell component (GridColDef['renderCell']), the same custom cell component is used in the grouping column.

You can opt out of this default behavior by returning params.value in renderCell for grouping rows instead:

const ratingColDef: GridColDef = {
  // ...
  renderCell: (params) => {
    if (params.rowNode.type === 'group') {
      return params.value;
    }

    return (
      // ...
    );
  },
};

Show values for the leaves

By default, the grouped rows display no value on their grouping columns' cells. Those cells are called "leaves."

If you want to display some value, you can provide a leafField property to the groupingColDef.

Hide the descendant count

Use the hideDescendantCount property of the groupingColDef to hide the number of descendants of a grouping row.

Hide the grouped columns

By default, the columns used to group the rows remains visible. For instance if you group by "director", you have two columns titled Director:

The grouped column (the column from which you grouped the rows)
The grouping column on which you can toggle the groups

To automatically hide the grouped columns, use the useKeepGroupedColumnsHidden utility hook. The hook automatically hides the columns when added to the model, and displays them when removed from it.

Below are two examples about how to use columnVisibilityModel or initialState with useKeepGroupedColumnsHidden hook. You can mix the two examples to support both at the same time.

// Usage with the initial state
const apiRef = useGridApiRef();

const initialState = useKeepGroupedColumnsHidden({
  apiRef,
  initialState: {
    rowGrouping: {
      model: ['company'],
    },
    columns: {
      // Other hidden columns
      columnVisibilityModel: { gross: false },
    },
  },
});

return <DataGridPremium {...data} apiRef={apiRef} initialState={initialState} />;

// Usage with the controlled model
const apiRef = useGridApiRef();

const [rowGroupingModel, setRowGroupingModel] = React.useState([
  'company',
  'director',
]);

const initialState = useKeepGroupedColumnsHidden({
  apiRef,
  rowGroupingModel,
});

return (
  <DataGridPremium
    {...data}
    apiRef={apiRef}
    initialState={initialState}
    rowGroupingModel={rowGroupingModel}
  />
);

Disable the row grouping

For all columns

You can disable row grouping by setting the disableRowGrouping prop to true.

It will disable all the features related to the row grouping, even if a model is provided.

For some columns

In case you need to disable grouping on specific column(s), set the groupable property on the respective column definition (GridColDef) to false. In the example below, the director column cannot be grouped. In all examples, the title and gross columns cannot be grouped.

Grouping non-groupable columns programmatically

To apply row grouping programmatically on non-groupable columns (columns with groupable: false in the column definition), you can provide row grouping model in one of the following ways:

Pass rowGrouping.model to the initialState prop. This will initialize the grouping with the provided model.
Provide the rowGroupingModel prop. This will control the grouping with the provided model.
Call the API method setRowGroupingModel. This will set the aggregation with the provided model.

In the following example, the column company is not groupable from the UI but the rowGroupingModel prop is passed to generate a read-only row group.

Using `groupingValueGetter` for complex grouping value

The grouping value has to be either a string, a number, null, or undefined. If your cell value is more complex, pass a groupingValueGetter property to the column definition to convert it into a valid value.

const columns: GridColDef[] = [
  {
    field: 'composer',
    groupingValueGetter: (value) => value.name,
  },
  // ...
];

Rows with missing groups

If the grouping key of a grouping criteria is null or undefined for a row, the data grid will consider that this row does not have a value for this group. and will inline it for those groups.

Group expansion

By default, all groups are initially displayed collapsed. You can change this behavior by setting the defaultGroupingExpansionDepth prop to expand all the groups up to a given depth when loading the data. If you want to expand the whole tree, set defaultGroupingExpansionDepth = -1

If you want to expand groups by default according to a more complex logic, use the isGroupExpandedByDefault prop which is a callback receiving the node as an argument. When defined, this callback will always have priority over the defaultGroupingExpansionDepth prop.

isGroupExpandedByDefault={
  node => node.groupingField === 'company' && node.groupingKey === '20th Century Fox'
}

Use the setRowChildrenExpansion method on apiRef to programmatically set the expansion of a row. Changing the expansion of a row emits a rowExpansionChange event, listen to it to react to the expansion change.

Customize grouping cell indent

To change the default cell indent, you can use the --DataGrid-cellOffsetMultiplier CSS variable:

<DataGridPremium
  sx={{
    // default value is 2
    '--DataGrid-cellOffsetMultiplier': 6,
  }}
/>

Sorting / Filtering

Single grouping column

When using rowGroupingColumnMode = "single", the default behavior is to:

sort each grouping criteria using the sortComparator of the column
apply the filterOperators of the top-level grouping criteria

If you are rendering leaves with the leafField property of groupingColDef, the sorting and filtering will be applied on the leaves based on the sortComparator and filterOperators of their original column.

You can force the filtering to be applied on another grouping criteria with the mainGroupingCriteria property of groupingColDef

Main grouping criteria

Multiple grouping columns

When using rowGroupingColumnMode = "multiple", the default behavior is to apply the sortComparator and filterOperators of the grouping criteria of each grouping column.

If you are rendering leaves on one of those columns with the leafField property of groupingColDef, the sorting and filtering will be applied on the leaves for this grouping column based on the sortComparator and filterOperators of the leave's original column.

If you want to render leaves but apply the sorting and filtering on the grouping criteria of the column, you can force it by setting the mainGroupingCriteria property groupingColDef to be equal to the grouping criteria.

In the example below:

the sorting and filtering of the company grouping column is applied on the company field
the sorting and filtering of the director grouping column is applied on the director field even though it has leaves

Get the rows in a group

You can use the apiRef.current.getRowGroupChildren method to get the id of all rows contained in a group. It will not contain the autogenerated rows (that is the subgroup rows or the aggregation footers).

const rows: GridRowId[] = apiRef.current.getRowGroupChildren({
  groupId: params.id,

  // If true, the rows will be in the order displayed on screen
  applySorting: true,

  // If true, only the rows matching the current filters will be returned
  applyFiltering: true,
});

If you want to get the row ids of a group given its grouping criteria, use getGroupRowIdFromPath

const rows = apiRef.current.getRowGroupChildren({
  groupId: getGroupRowIdFromPath([{ field: 'company', key: 'Disney Studios' }]),
});

Click on a group row to log its children here

Row group panel 🚧

With this panel, your users will be able to control which columns are used for grouping just by dragging them inside the panel.

Accessibility changes in v8

The Data Grid v8 with row grouping feature will improve the accessibility and will be more aligned with the WAI-ARIA authoring practices.

You can start using the new accessibility features by enabling ariaV8 experimental feature flag:

<DataGridPremium experimentalFeatures={{ ariaV8: true }} />

Adds the field to the row grouping model.

Signature:

addRowGroupingCriteria: (groupingCriteriaField: string, groupingIndex?: number) => void

removeRowGroupingCriteria()

Remove the field from the row grouping model.

Signature:

removeRowGroupingCriteria: (groupingCriteriaField: string) => void

setRowGroupingCriteriaIndex()

Sets the grouping index of a grouping criteria.

Signature:

setRowGroupingCriteriaIndex: (groupingCriteriaField: string, groupingIndex: number) => void

setRowGroupingModel()

Sets the columns to use as grouping criteria.

Signature:

setRowGroupingModel: (model: GridRowGroupingModel) => void

Data Grid - Row grouping

Grouping criteria

Initialize the row grouping

Controlled row grouping

Grouping columns

Single grouping column

Multiple grouping columns

Custom grouping column

Grouping rows with custom cell renderer

Show values for the leaves

Hide the descendant count

Hide the grouped columns

Disable the row grouping

For all columns

For some columns

Grouping non-groupable columns programmatically

Using `groupingValueGetter` for complex grouping value

Rows with missing groups

Group expansion

Customize grouping cell indent

Sorting / Filtering

Single grouping column

Multiple grouping columns

Get the rows in a group

Row group panel 🚧

Accessibility changes in v8

Full example

Advanced use cases

apiRef

Signature:

Signature:

Signature:

Signature:

API