跳转到内容

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: GridEventsStr,
    handler: (params: any, event: MuiEvent, details: GridCallbackDetails) => void,
    options?: EventListenerOptions,
) => () => 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
cellClick
Fired when a cell is clicked.
Params: GridCellParams
Event: MuiEvent<React.MouseEvent<HTMLElement>>
cellDoubleClick
Fired when a cell is double-clicked.
Params: GridCellParams
Event: MuiEvent<React.MouseEvent<HTMLElement>>
cellEditCommit
Fired when the props of the edit input are committed.
Params: GridCellEditCommitParams
Event: MuiEvent<MuiBaseEvent>
cellEditStart
Fired when the cell turns to edit mode.
Params: GridCellEditStartParams
Event: MuiEvent<React.MouseEvent<HTMLElement> | React.KeyboardEvent<HTMLElement>>
cellEditStop
Fired when the cell turns back to view mode.
Params: GridCellEditStopParams
Event: MuiEvent<MuiBaseEvent>
cellFocusIn
Fired when a cell gains focus.
Params: GridCellParams
Event: MuiEvent<{}>
cellFocusOut
Fired when a cell loses focus.
Params: GridCellParams
Event: MuiEvent<MuiBaseEvent>
cellKeyDown
Fired when a keydown event happens in a cell.
Params: GridCellParams
Event: MuiEvent<React.KeyboardEvent<HTMLElement>>
cellModesModelChange
Fired when the model that controls the cell modes changes.
Params: GridCellModesModel
Event: MuiEvent<{}>
cellMouseDown
Fired when a mousedown event happens in a cell.
Params: GridCellParams
Event: MuiEvent<React.MouseEvent<HTMLElement>>
cellMouseUp
Fired when a mouseup event happens in a cell.
Params: GridCellParams
Event: MuiEvent<React.MouseEvent<HTMLElement>>
columnHeaderClick
Fired when a column header is clicked
Params: GridColumnHeaderParams
Event: MuiEvent<React.MouseEvent<HTMLElement>>
columnHeaderDoubleClick
Fired when a column header is double-clicked.
Params: GridColumnHeaderParams
Event: MuiEvent<React.MouseEvent<HTMLElement>>
columnHeaderKeyDown
Fired when a key is pressed in a column header. It's mapped do the keydown DOM event.
Params: GridColumnHeaderParams
Event: MuiEvent<React.KeyboardEvent<HTMLElement>>
columnOrderChange
Fired when the user ends reordering a column.
Params: GridColumnOrderChangeParams
Event: MuiEvent<{}>
columnResize
Fired during the resizing of a column.
Params: GridColumnResizeParams
Event: MuiEvent<MouseEvent>
columnResizeStart
Fired when the user starts resizing a column.
Params: { field: string }
Event: MuiEvent<React.MouseEvent<HTMLElement>>
columnResizeStop
Fired when the user stops resizing a column.
Params: null
Event: MuiEvent<MouseEvent>
columnsChange
Fired when the columns state is changed.
Params: string[]
Event: MuiEvent<{}>
columnVisibilityChange
Fired when a column visibility changes. It is not fired when the columnVisibilityModel is controlled or initialized. It is not fired when toggling all column's visibility at once.
Params: GridColumnVisibilityChangeParams
Event: MuiEvent<{}>
columnVisibilityModelChange
Fired when the column visibility model changes.
Params: GridColumnVisibilityModel
Event: MuiEvent<{}>
columnWidthChange
Fired when the width of a column is changed.
Params: GridColumnResizeParams
Event: MuiEvent<MouseEvent | {}>
componentError
Fired when an exception is thrown in the grid.
Params: any
Event: MuiEvent<{}>
debouncedResize
Fired when the grid is resized with a debounced time of 60ms.
Params: ElementSize
Event: MuiEvent<{}>
editCellPropsChange
Fired when the props of the edit cell changes.
Params: GridEditCellPropsParams
Event: MuiEvent<React.SyntheticEvent<HTMLElement> | {}>
editRowsModelChange
Fired when the row editing model changes.
Params: GridEditRowsModel
Event: MuiEvent<{}>
filterModelChange
Fired when the filter model changes.
Params: GridFilterModel
Event: MuiEvent<{}>
headerSelectionCheckboxChange
Fired when the value of the selection checkbox of the header is changed
Params: GridHeaderSelectionCheckboxParams
Event: MuiEvent<{}>
menuClose
Fired when the grid menu is closed.
Params: GridMenuParams
Event: MuiEvent<{}>
menuOpen
Fired when the menu is opened.
Params: GridMenuParams
Event: MuiEvent<{}>
pageChange
Fired when the page changes.
Params: number
Event: MuiEvent<{}>
pageSizeChange
Fired when the page size changes.
Params: number
Event: MuiEvent<{}>
preferencePanelClose
Fired when the preference panel is closed.
Params: GridPreferencePanelParams
Event: MuiEvent<{}>
preferencePanelOpen
Fired when the preference panel is opened.
Params: GridPreferencePanelParams
Event: MuiEvent<{}>
resize
Fired when the grid is resized.
Params: ElementSize
Event: MuiEvent<{}>
rowClick
Fired when a row is clicked. Not fired if the cell clicked is from an interactive column (actions, checkbox, etc).
Params: GridRowParams
Event: MuiEvent<React.MouseEvent<HTMLElement>>
rowDoubleClick
Fired when a row is double-clicked.
Params: GridRowParams
Event: MuiEvent<React.MouseEvent<HTMLElement>>
rowEditCommit
Fired when the props of the edit input are committed.
Params: GridRowId
Event: MuiEvent<MuiBaseEvent>
rowEditStart
Fired when the row turns to edit mode.
Params: GridRowEditStartParams
Event: MuiEvent<React.MouseEvent<HTMLElement> | React.KeyboardEvent<HTMLElement>>
rowEditStop
Fired when the row turns back to view mode.
Params: GridRowEditStopParams
Event: MuiEvent<MuiBaseEvent>
rowGroupingModelChange
Fired when the row grouping model changes.
Params: GridRowGroupingModel
Event: MuiEvent<{}>
rowModesModelChange
Fired when the model that controls the row modes changes.
Params: GridRowModesModel
Event: MuiEvent<{}>
rowMouseEnter
Fired when the mouse enters the row. Called with a GridRowParams object.
Params: GridRowParams
Event: MuiEvent<React.MouseEvent<HTMLElement>>
rowMouseLeave
Fired when the mouse leaves the row. Called with a GridRowParams object.
Params: GridRowParams
Event: MuiEvent<React.MouseEvent<HTMLElement>>
rowOrderChange
Fired when the user ends reordering a row.
Params: GridRowOrderChangeParams
Event: MuiEvent<{}>
rowSelectionCheckboxChange
Fired when the value of the selection checkbox of a row is changed
Params: GridRowSelectionCheckboxParams
Event: MuiEvent<React.ChangeEvent<HTMLElement>>
rowsScroll
Fired during the scroll of the grid viewport.
Params: GridScrollParams
Event: MuiEvent<React.UIEvent | MuiBaseEvent>
rowsScrollEnd
Fired when scrolling to the bottom of the grid viewport.
Params: GridRowScrollEndParams
Event: MuiEvent<{}>
selectionChange
Fired when the selection state of one or multiple rows changes.
Params: GridSelectionModel
Event: MuiEvent<{}>
sortModelChange
Fired when the sort model changes.
Params: GridSortModel
Event: MuiEvent<{}>
stateChange
Fired when the state of the grid is updated.
Params: any
Event: MuiEvent<{}>
unmount
Fired when the grid is unmounted.
Event: MuiEvent<{}>
viewportInnerSizeChange
Fired when the inner size of the viewport changes. Called with an ElementSize object.
Params: ElementSize
Event: MuiEvent<{}>