diff --git a/docs/data/data-grid/cell-selection/cell-selection.md b/docs/data/data-grid/cell-selection/cell-selection.md index 86764f01e38f0..e2a3b63f3a37a 100644 --- a/docs/data/data-grid/cell-selection/cell-selection.md +++ b/docs/data/data-grid/cell-selection/cell-selection.md @@ -4,35 +4,39 @@ title: Data Grid - Cell selection # Data Grid - Cell selection [](/x/introduction/licensing/#premium-plan 'Premium plan') -

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

+

Let users select individual cells or a range of cells.

-The Data Grid has, by default, the ability to select rows. -On the Data Grid Premium, you can also enable the ability to select cells with the `cellSelection` prop. +## Enabling cell selection + +By default, the Data Grid lets users select individual rows. +With the Data Grid Premium, you can apply the `cellSelection` prop to let users select individual cells or ranges of cells. ```tsx ``` -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. +## Selecting cells + +With the `cellSelection` prop applied, users can select a single cell by clicking on it, or by pressing Shift+Space when the cell is in focus. +Select multiple cells by holding Cmd (or Ctrl on Windows) while clicking on them. +Hold Cmd (or Ctrl on Windows) and click on a selected cell to deselect it. -To select all cells within a range, you can use one of the interactions available: +To select a range of cells, users can: -- **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 +- Click on a cell, drag the mouse over nearby cells, and then release. +- Click on a cell, then hold Shift and click on another cell. If a third cell is clicked then the selection will restart from the last clicked cell. +- Use the arrow keys to focus on a cell, then hold Shift and navigate to another cell—if Shift is released and pressed again then the selection will restart from the last focused cell. -The following demo allows to explore the cell selection feature. -It has [row selection](/x/react-data-grid/row-selection/) disabled, but it's possible to set both selections to work in parallel. +Try out the various actions to select cells in the demo below—you can toggle [row selection](/x/react-data-grid/row-selection/) on and off to see how these two selection features can work in parallel. {{"demo": "CellSelectionGrid.js", "bg": "inline"}} -## Controlled cell selection +## Controlling cell selection -You can control which cells are selected with the `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. +You can control which cells are selected using the `cellSelectionModel` prop. +This prop accepts an object with keys corresponding to the row IDs that contain selected cells. +The value of each key is itself an object, which has a column field for a key and a boolean value for its selection state. +You can set this to `true` to select a cell or `false` to deselect it. Removing the field from the object also deselects the cell. ```tsx @@ -46,35 +50,35 @@ Removing the field from the object also deselects the cell. When a new selection is made, the callback passed to the `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. +The following demo shows how these props can be combined to create an Excel-like formula field—try updating multiple cells at once by selecting them and entering a new value in the field at the top. {{"demo": "CellSelectionFormulaField.js", "bg": "inline"}} -## 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 +## Customizing range styles -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. +When multiple selected cells form a continuous range of any size, the following class names are applied to the cells at the edges: -{{"demo": "CellSelectionRangeStyling.js", "bg": "inline"}} +- `MuiDataGrid-cell--rangeTop`: to all cells in the first row of the range +- `MuiDataGrid-cell--rangeBottom`: to all cells in the last row of the range +- `MuiDataGrid-cell--rangeLeft`: to all cells in the first column of the range +- `MuiDataGrid-cell--rangeRight`: to all cells in the last column of the range :::info -If a single cell is selected, all classes above are applied to the same element. +When a single cell is selected, all classes above are applied to that element. ::: +You can use these classes to create CSS selectors targeting specific corners of each range—for example, the demo below adds a border around the outside of the range. + +{{"demo": "CellSelectionRangeStyling.js", "bg": "inline"}} + ## apiRef -The grid exposes a set of methods that enables all of these features using the imperative `apiRef`. To know more about how to use it, check the [API Object](/x/react-data-grid/api-object/) section. +The Data Grid exposes a set of methods via the `apiRef` object that are used in the implementation of the cell selection feature. +The reference below describes the relevant functions. +See [API object](/x/react-data-grid/api-object/) for more details. :::warning -Only use this API as the last option. Give preference to the props to control the Data Grid. +This API should only be used as a last resort—give preference to props for controlling the Data Grid. ::: {{"demo": "CellSelectionApiNoSnap.js", "bg": "inline", "hideToolbar": true}} diff --git a/docs/pages/x/api/data-grid/grid-cell-selection-api.json b/docs/pages/x/api/data-grid/grid-cell-selection-api.json index ff95e4d3138ac..e874c8338bb23 100644 --- a/docs/pages/x/api/data-grid/grid-cell-selection-api.json +++ b/docs/pages/x/api/data-grid/grid-cell-selection-api.json @@ -4,7 +4,7 @@ "properties": [ { "name": "getCellSelectionModel", - "description": "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.", + "description": "Returns an object containing the selection state of the cells. The keys of the object correspond to the row IDs. The value of each key is also an object, which has a column field for a key and a boolean value for its selection state.", "type": "() => GridCellSelectionModel" }, { @@ -24,7 +24,7 @@ }, { "name": "setCellSelectionModel", - "description": "Updates the selected cells to be those passed to the newModel argument. Any cell already selected will be unselected.", + "description": "Updates the cell selection model according to the value passed to the newModel argument. Any cell already selected will be unselected.", "type": "(newModel: GridCellSelectionModel) => void" } ] diff --git a/docs/translations/api-docs/data-grid/grid-api.json b/docs/translations/api-docs/data-grid/grid-api.json index ea6c6cfe190ef..1c9c515175209 100644 --- a/docs/translations/api-docs/data-grid/grid-api.json +++ b/docs/translations/api-docs/data-grid/grid-api.json @@ -33,7 +33,7 @@ "description": "Gets the GridCellParams object that is passed as argument in events." }, "getCellSelectionModel": { - "description": "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." + "description": "Returns an object containing the selection state of the cells.
The keys of the object correspond to the row IDs.
The value of each key is also an object, which has a column field for a key and a boolean value for its selection state." }, "getCellValue": { "description": "Gets the value of a cell at the given id and field." @@ -149,7 +149,7 @@ "description": "Sets the focus to the cell at the given id and field." }, "setCellSelectionModel": { - "description": "Updates the selected cells to be those passed to the newModel argument.
Any cell already selected will be unselected." + "description": "Updates the cell selection model according to the value passed to the newModel argument.
Any cell already selected will be unselected." }, "setColumnHeaderFilterFocus": { "description": "Sets the focus to the column header filter at the given field." diff --git a/packages/x-data-grid-premium/src/hooks/features/cellSelection/gridCellSelectionInterfaces.ts b/packages/x-data-grid-premium/src/hooks/features/cellSelection/gridCellSelectionInterfaces.ts index ded538573b13b..f13137b7aa640 100644 --- a/packages/x-data-grid-premium/src/hooks/features/cellSelection/gridCellSelectionInterfaces.ts +++ b/packages/x-data-grid-premium/src/hooks/features/cellSelection/gridCellSelectionInterfaces.ts @@ -15,13 +15,13 @@ export interface GridCellSelectionApi { isCellSelected: (id: GridRowId, field: GridColDef['field']) => boolean; /** * 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. + * The keys of the object correspond to the row IDs. + * The value of each key is also an object, which has a column field for a key and a boolean value for its selection state. * @returns {GridCellSelectionModel} Object containing the selection state of the cells */ getCellSelectionModel: () => GridCellSelectionModel; /** - * Updates the selected cells to be those passed to the `newModel` argument. + * Updates the cell selection model according to the value passed to the `newModel` argument. * Any cell already selected will be unselected. * @param {GridCellSelectionModel} newModel The cells to select. */