Data Grid - Cell selection

Cell selection allows the user to select individual cells or a range of cells.

The Data Grid has, by default, the ability to select rows. On the DataGridPremium, you can also enable the ability to select cells with the unstable_cellSelection prop.

<DataGridPremium unstable_cellSelection />

To select a single cell, click on it or, with the cell focused, press Shift+Space. Multiple cells can be selected by holding Ctrl while clicking the cells. A cell can be deselected by also clicking it while Ctrl is pressed.

To select all cells within a range, you can use one of the interactions available:

Mouse drag: Click on a cell, then drag the mouse over another cell and release it
Shift + click: Click on a cell and, while holding Shift, click on another cell—if a third cell is clicked the selection will restart from the last clicked cell
Shift + arrow keys: Using the arrow keys, focus on a cell, then hold Shift and navigate to another cell—if Shift is released and pressed again, the selection will restart from the last focused cell

The following demo allows to explore the cell selection feature. It has row selection disabled, but it's possible to set both selections to work in parallel.

<Button sx={{ mb: 2 }} onClick={() => setRowSelection(!rowSelection)}>
  Toggle row selection
</Button>
<div style={{ height: 400 }}>
  <DataGridPremium
    rowSelection={rowSelection}
    checkboxSelection={rowSelection}
    unstable_cellSelection
    {...data}
  />
</div>

<Button sx={{ mb: 2 }} onClick={() => setRowSelection(!rowSelection)}>
  Toggle row selection
</Button>
<div style={{ height: 400 }}>
  <DataGridPremium
    rowSelection={rowSelection}
    checkboxSelection={rowSelection}
    unstable_cellSelection
    {...data}
  />
</div>

Press Enter to start editing

Controlled cell selection

You can control which cells are selected with the unstable_cellSelectionModel prop. This props accepts an object whose keys are the row IDs that contain selected cells. The value of each key is another object, which in turn has column fields as keys, each with a boolean value to represent their selection state. You can set true to select the cell or false to deselect a cell. Removing the field from the object also deselects the cell.

// Selects the cell with field=name from row with id=1
<DataGridPremium unstable_cellSelectionModel={{ 1: { name: true } }} />

// Unselects the cell with field=name from row with id=1
<DataGridPremium unstable_cellSelectionModel={{ 1: { name: false } }} />

When a new selection is made, the callback passed to the unstable_onCellSelectionModelChange prop is called with the updated model. Use this value to update the current model.

The following demo shows how these props can be combined to create an Excel-like formula field.

Selected cell value

Customize range styling

When multiple selected cells make a range, specific class names are applied to the cells at the edges of this range. The class names applied are the following:

MuiDataGrid-cell--rangeTop: applied to all cells of the first row of the range
MuiDataGrid-cell--rangeBottom: applied to all cells of the last row of the range
MuiDataGrid-cell--rangeLeft: applied to all cells of the first column of the range
MuiDataGrid-cell--rangeRight: applied to all cells of the last column of the range

You can use these classes to create CSS selectors targeting specific corners of each range. The demo below shows how to add a border around the range.

<StyledDataGridPremium rowSelection={false} unstable_cellSelection {...data} />

<StyledDataGridPremium rowSelection={false} unstable_cellSelection {...data} />

Press Enter to start editing

apiRef

The grid exposes a set of methods that enables all of these features using the imperative apiRef.

unstable_getCellSelectionModel()

Returns an object containing the selection state of the cells. The keys of the object correpond to the row IDs. The value of each key is another object whose keys are the fields and values are the selection state.

Signature:

unstable_getCellSelectionModel: () => GridCellSelectionModel

unstable_getSelectedCellsAsArray()

Returns an array containg only the selected cells. Each item is an object with the ID and field of the cell.

Signature:

unstable_getSelectedCellsAsArray: () => GridCellCoordinates[]

unstable_isCellSelected()

Determines if a cell is selected or not.

Signature:

unstable_isCellSelected: (id: GridRowId, field: GridColDef['field']) => boolean

unstable_selectCellRange()

Selects all cells that are inside the range given by start and end coordinates.

Signature:

unstable_selectCellRange: (start: GridCellCoordinates, end: GridCellCoordinates, keepOtherSelected?: boolean) => void

unstable_setCellSelectionModel()

Updates the selected cells to be those passed to the newModel argument. Any cell already selected will be unselected.

Signature:

unstable_setCellSelectionModel: (newModel: GridCellSelectionModel) => void