Checkbox Selection in React Data Grid

The Syncfusion® React Data Grid provides checkbox row selection for selecting individual rows, multiple rows, or all rows at once. Selections are preserved across operations such as paging, sorting, filtering, and data refresh, ensuring consistency throughout grid interactions. The feature also supports bulk operations, including deleting selected records or all records directly within the grid.

Enable checkbox selection

Checkbox selection is enabled by defining a column with the type property set to Checkbox, which automatically displays a checkbox in each row and in the column header. By default, the grid is configured for multiple selection mode, allowing several rows to be selected at once. To change the selection mode to single selection with checkbox, set the selectionSettings.mode property to Single.

Selection persists across operations with the selectionSettings.persistSelection property, which is enabled by default when rendering checkboxes. For selection persistence in the Data Grid component, designate one column as the primary key using the isPrimaryKey property.

Disable the select-all options

By default, setting column type to Checkbox adds a column with checkboxes for row selection, including a header checkbox that allows selecting all rows at once. To hide the header checkbox and disable the select all option, set the headerCheckbox property to false in the column configuration.

Persistent checkbox selection

The Data Grid component's checkbox selection supports persistent selection, which maintains selected rows during operations such as sorting, paging, filtering, refreshing, etc. This persistence is achieved through the primary key of a unique column, ensuring that row selections remain consistent across grid actions.

When checkbox selection enabled, selection persistence is activated by default. If you prefer selections not to be maintained after a grid refresh, disable persistence by setting selectionSettings.persistSelection to false.

When persistence is disabled:

The grid does not maintain row selections during actions such as sorting, paging, filtering, searching, or content refreshing.
Selections are automatically cleared after every grid action.
The select all option applies only to the current page of data, not across all pages.

Select rows only via checkbox

When the selectionSettings.checkboxOnly property is set to true, grid rows can be selected only by clicking the checkbox in the column. This prevents row selection through other interactions such as clicking on the cell or row itself. This ensures that selection is strictly controlled through checkboxes, providing a consistent and predictable experience.

Delete all selected records

The Data Grid supports deleting selected records either from the current page only or across all pages. The exact behavior depends on whether the grid is bound to a local data source or a remote data source.

Local data: All records are already loaded and directly accessible in the grid. Deletion can be performed immediately either for the selected records on the current page or for the entire dataset without any server communication.

Remote data: All actions are server-driven, so deletion requires sending a payload. The delete payload structure will differ depending on whether the operation applies only to the selected records on the current page or to all selected records across the dataset.

Delete all records:

This request indicates that all records in the grid should be deleted, and the server responds by removing every record from the remote data source.

Delete records from current page only:

This request indicates that only the records selected on the current page should be deleted, and the server removes them based on the provided primary key values.

Delete loaded records only

The Data Grid’s deletion functionality applies only to records that have been loaded and are currently visible, rather than removing the entire dataset. This behavior is enabled by configuring selectionSettings:{ autoSelectMode:'Intermediate'}, which restricts deletion to records that have already been fetched and displayed in the grid. Records that are not yet loaded, including those on unvisited pages, remain unaffected.

When a delete request is triggered in this mode, the grid sends the selected primary keys in the payload along with the delete URL, allowing the server to identify and remove only the specified records.

Retrieving selected rows

The Data Grid provides the getSelectedRecords() method to retrieve details of selected records. The return value of this method varies based on the data source configuration, persistence settings, and selection mode, especially when the "Select All" checkbox is activated.

Local data

Returns all selected records across all pages when the entire dataset is loaded in the grid. If selectionSettings.persistSelection is disabled, it returns only the selected records from the current page, as selections on other pages are not preserved.

Remote data

The method returns a selection metadata object, since the grid does not fetch all records from the server.

Default mode:

The Data Grid's checkbox selection automatically uses default mode when selectionSettings.autoSelectMode is set to "Default" (this is the built-in default behavior). In this mode, deletion requests can be handled in three distinct ways:

i) Delete all the records: This option deletes all records in the grid. Since no primary keys are provided for exclusion, the server interprets the request as a command to remove every record without keeping any.
```
{ "isSelectAll": true, "primaryKeys": [] }  
```
ii) Delete all except unselected records: This option deletes all records across the grid while keeping those explicitly excluded as unselected rows. The server processes the request by removing every record except the ones identified by the provided primary key values.
```
{ "isSelectAll": true, "primaryKeys": ["10001","10002"] }  
```
iii) Delete specific rows: This option deletes only the rows that are explicitly selected in the grid. The server processes the request by removing the records identified through the provided primary key values, with isSelectAll set to false.
```
{ "isSelectAll": false, "primaryKeys": ["10001","10002"] }  
```
Intermediate mode:

In intermediate mode, when selectionSettings.autoSelectMode is set to "Intermediate", the Data Grid only tracks selections from pages that have already been loaded or visited. Because the grid does not fetch the entire dataset, deletions are limited to the rows currently loaded in the grid. Therefore, a delete request contains payloads limited to those loaded rows:
```
{ "isSelectAll": false, "primaryKeys": ["10001", "10002"] }
```

The following example shows the return type of the getSelectedRecords() method when the grid is bound to local data.