Skip to content

🎉 v5 is out! Head to the documentation to get started.

Data Grid - Events

The data grid emits events that can be subscribed to attach custom behavior.

Subscribing to events

You can subscribe to one of the events emitted by calling apiRef.current.subscribeEvent() with the name of the event and a handler. The handler will be called with three arguments:

  1. an object with information related to the event
  2. a MuiEvent containing the DOM event or the React synthetic event, when available
  3. a GridCallbackDetails containing the GridApi only if DataGridPro is being used.
/**
 * Allows to register a handler for an event.
 * @param event The name of event
 * @param handler The handler to be called
 * @param options Additional options for this listener
 * @returns A function to unsubscribe from this event
 */
subscribeEvent: (
  event: string,
  handler: (params: any, event: MuiEvent, details: GridCallbackDetails) => void,
  options?: GridSubscribeEventOptions,
) => () => void;

The following demo shows how to subscribe to the columnResize event. Try it by resizing the columns.

<div style={{ height: 180, width: '100%' }}>
  <DataGridPro apiRef={apiRef} {...data} />
</div>
{message && (
  <Alert severity="info" style={{ marginTop: 8 }}>
    {message}
  </Alert>
)}

Disabling the default behavior

Depending on the use case, it might be necessary to disable the default action taken by an event. The MuiEvent passed to the event handler has a defaultMuiPrevented property to control when the default behavior can be executed or not. Set it to true to block the default handling of an event and implement your own.

<DataGrid
  onCellClick={(params: GridCellParams, event: MuiEvent<React.MouseEvent>) => {
    event.defaultMuiPrevented = true;
  }}
/>

Usually, double clicking a cell will put it into edit mode. The following example changes this behavior by also requiring CTRL to be pressed.

<DataGrid
  onCellDoubleClick={(params, event) => {
    if (!event.ctrlKey) {
      event.defaultMuiPrevented = true;
    }
  }}
  {...data}
/>

Catalog of events

NameDescription
cellBlurFired when the blur event of a cell is triggered. Called with a GridCellParams object.
cellClickFired when a cell is clicked. Called with a GridCellParams object.
cellDoubleClickFired when a cell is double-clicked. Called with a GridCellParams object.
cellEditCommitFired when the props of the edit input are committed. Called with a GridEditCellPropsParams object.
cellEditStartFired when the cell turns to edit mode. Called with a GridCellParams object.
cellEditStopFired when the cell turns back to view mode. Called with a GridCellParams object.
cellEnterFired when a mouseenter event happens in a cell. Called with a GridCellParams object.
cellFocusFired when a cell gains focus. Called with a GridCellParams object.
cellFocusInFired when a cell gains focus. Called with a GridCellParams object.
cellFocusOutFired when a cell loses focus. Called with a GridCellParams object.
cellKeyDownFired when a keydown event happens in a cell. Called with a GridCellParams object.
cellLeaveFired when a mouseleave event happens in a cell. Called with a GridCellParams object.
cellMouseDownFired when a mousedown event happens in a cell. Called with a GridCellParams object.
cellMouseUpFired when a mouseup event happens in a cell. Called with a GridCellParams object.
cellOutFired when a mouseout event happens in a cell. Called with a GridCellParams object.
cellOverFired when a mouseover event happens in a cell. Called with a GridCellParams object.
columnHeaderClickFired when a column header is clicked. Called with a GridColumnHeaderParams object.
columnHeaderDoubleClickFired when a column header is double-clicked. Called with a GridColumnHeaderParams object.
columnHeaderKeyDownFired when a key is pressed in a column header. It's mapped do the keydown DOM event. Called with a GridColumnHeaderParams object.
columnOrderChangeFired when the user ends reordering a column.
columnResizeFired during the resizing of a column. Called with a GridColumnResizeParams object.
columnResizeStartFired when the user starts resizing a column. Called with an object { field: string }.
columnResizeStopFired when the user stops resizing a column. Called with an object { field: string }.
columnsChangeFired when the columns state is changed. Called with an array of strings corresponding to the field names.
columnVisibilityChangeFired when a column visibility changes. Called with a GridColumnVisibilityChangeParams object.
columnWidthChangeFired when the width of a column is changed. Called with a GridColumnResizeParams object.
componentErrorFired when an exception is thrown in the grid.
debouncedResizeFired when the grid is resized with a debounced time of 60ms. Called with a ElementSize object.
editCellPropsChangeFired when the props of the edit cell changes. Called with a GridEditCellPropsParams object.
editRowsModelChangeFired when the row editing model changes. Called with a GridEditRowModelParams object.
filterModelChangeFired when the filter model changes. Called with a GridFilterModel object.
pageChangeFired when the page changes.
pageSizeChangeFired when the page size changes.
resizeFired when the grid is resized. Called with a ElementSize object.
rowClickFired when a row is clicked. Called with a GridRowParams object.
rowDoubleClickFired when a row is double-clicked. Called with a GridRowParams object.
rowEditCommitFired when the props of the edit input are committed. Called with the GridRowId of the row.
rowEditStartFired when the row turns to edit mode. Called with a GridCellParams object.
rowEditStopFired when the row turns back to view mode. Called with a GridCellParams object.
rowEnterFired when a mouseenter event happens in a row. Called with a GridRowParams object.
rowLeaveFired when a mouseleave event happens in a row. Called with a GridRowParams object.
rowOutFired when a mouseout event happens in a row. Called with a GridRowParams object.
rowOverFired when a mouseover event happens in a row. Called with a GridRowParams object.
rowsScrollFired during the scroll of the grid viewport. Called with a GridScrollParams object.
rowsScrollEndFired when scrolling to the bottom of the grid viewport. Called with a GridRowScrollEndParams object.
selectionChangeFired when the selection state of one or multiple rows changes. Called with a GridSelectionModelChangeParams object.
sortModelChangeFired when the sort model changes. Called with a GridSortModelParams object.
stateChangeFired when the state of the grid is updated. Called with a GridState object.
unmountFired when the grid is unmounted.
viewportRowsChangeFired when the rows in the viewport is changed. Called with a GridViewportRowsChange object.