Data Grid - Server-side row grouping

Implement row grouping with server-side data in the Data Grid using the Data Source layer.

The Data Grid Premium's row grouping feature lets users create subsets of rows based on repeated column values or custom functions. The Grid can render grouped rows from server-side data using the Data Source layer.

The following demo uses autogenerated data from a dataset of commodities to simulate server-side row grouping.

<Button onClick={loadNewData}>Regenerate Data</Button>

<div style={{ height: 450, position: 'relative' }}>
  <DataGridPremium
    columns={columns}
    dataSource={dataSource}
    apiRef={apiRef}
    initialState={initialState}
    showToolbar
    groupingColDef={groupingColDef}
  />
</div>

<Button onClick={loadNewData}>Regenerate Data</Button>

<div style={{ height: 450, position: 'relative' }}>
  <DataGridPremium
    columns={columns}
    dataSource={dataSource}
    apiRef={apiRef}
    initialState={initialState}
    showToolbar
    groupingColDef={groupingColDef}
  />
</div>

Press Enter to start editing

Prerequisites

Server-side row grouping is an extension of its client-side counterpart, so we recommend reviewing Row grouping (client side) to understand the underlying data structures and core implementation before proceeding.

To be able to dynamically load row-grouping data from the server, including lazy-loading of children, you must create a Data Source and pass the dataSource prop to the Data Grid, as detailed in the Server-side data overview.

Implementating server-side row grouping

The Data Source requires the following props to implement row grouping:

getGroupKey(): Returns the group key for the row.
getChildrenCount(): Returns the number of children for the row; returns -1 if there are children present but the count is not available.

const customDataSource: GridDataSource = {
  getRows: async (params) => {
    // Fetch the data from the server
  },
  getGroupKey: (row) => {
    // Return the group key for the row, e.g. `name`
    return row.name;
  },
  getChildrenCount: (row) => {
    // Return the number of children for the row
    return row.childrenCount;
  },
};

In addition to groupKeys, the getRows() callback receives a groupFields parameter. This corresponds to the current rowGroupingModel. Use groupFields on the server to group the data for each getRows() call.

const getRows: async (params) => {
  const urlParams = new URLSearchParams({
    // Example: JSON.stringify(['20th Century Fox', 'James Cameron'])
    groupKeys: JSON.stringify(params.groupKeys),
    // Example: JSON.stringify(['company', 'director'])
    groupFields: JSON.stringify(params.groupFields),
  });
  const getRowsResponse = await fetchRows(
    // Server should group the data based on `groupFields` and
    // extract the rows for the nested level based on `groupKeys`.
    `https://mui.com/x/api/data-grid?${urlParams.toString()}`,
  );
  return {
    rows: getRowsResponse.rows,
    rowCount: getRowsResponse.rowCount,
  };
}

With the required props and parameters in place, server-side row grouping should now be implemented in your Data Grid, as shown in the demo below:

<Button
  onClick={() => {
    apiRef.current?.dataSource.cache.clear();
  }}
>
  Clear cache
</Button>

<div style={{ height: 400, position: 'relative' }}>
  <DataGridPremium
    columns={columns}
    dataSource={dataSource}
    apiRef={apiRef}
    initialState={initialState}
  />
</div>

<Button
  onClick={() => {
    apiRef.current?.dataSource.cache.clear();
  }}
>
  Clear cache
</Button>

<div style={{ height: 400, position: 'relative' }}>
  <DataGridPremium
    columns={columns}
    dataSource={dataSource}
    apiRef={apiRef}
    initialState={initialState}
  />
</div>

Press Enter to start editing

Error handling

If an error occurs during a getRows() call, the Data Grid displays an error message in the row group cell. onDataSourceError() is also triggered with an error containing the params described in Server-side data overview—Error handling.

The demo below renders a custom Snackbar component to display an error message when the requests fail, which you can simulate using the checkbox and the Refetch rows button at the top.

Make the requests fail

Group expansion

Group expansion with server-side row grouping works similarly to how it's described in the client-side row grouping documentation. The difference is that the data is not initially available and is fetched automatically after the Data Grid is mounted based on the defaultGroupingExpansionDepth and isGroupExpandedByDefault() props in a waterfall manner.

The following demo uses defaultGroupingExpansionDepth={-1} to expand all groups by default.