Selection

Selection is a DataGrid feature that allows an end-user to mark certain rows in a grid as selected. Selected rows have a differing appearance from regular rows. After a row is selected, its data may be processed the way you require.

NOTE
Only data rows can be selected.

In the following subtopics, you will learn how to configure selection in a UI and in code, select rows initially and use the keyboard to perform selection.

Selecting in UI

Selection in the DataGrid widget can be carried out in a single or multiple mode. To specify the mode, set the selection | mode option to either 'single' or 'multiple' as shown in the code snippet below. Setting this option is obligatory, because selection is disabled by default.

JavaScript
$("#gridContainer").dxDataGrid({
    // ...
    selection: {
        mode: 'single' // 'multiple'
    }
});

Single Mode

A single mode is preferable when you only need one grid row to be selected at a time. To select a row in this mode, an end-user must click this row. When a user clicks another row, the formerly selected one becomes unselected.

Additionally, a selected row can be deselected by a mouse click as you press the CTRL key. For information on keyboard shortcuts in DataGrid, see the Keyboard Navigation and Selecting Using Keyboard Shortcuts topics.

The animation below demonstrates how to perform selection in a single mode.

DevExtreme DataGrid Selection

View Demo

Multiple Mode

When you need to select several rows at once, set the multiple selection mode. This mode supplements a grid with a selection column that contains check boxes accompanying each grid row. A user can select rows using these check boxes. In a multiple mode, when a user clicks different rows, the grid behaves like the selection mode is single (see the previous subtopic), but once the user clicks a checkbox, grid behavior changes. From this point forward, clicking a row selects it. Grid behavior reverts to single-like when the user decides to deselect all grid rows by unchecking all check boxes.

DevExtreme DataGrid Selection

The selection column enables a user to select all rows at once. This feature is controlled by the allowSelectAll option of the selection object, which is true by default. To disable the feature, set this option to false. Note that the user will still be able to deselect all rows at once.

JavaScript
$("#gridContainer").dxDataGrid({
    // ...
    selection: {
        mode: 'multiple',
        allowSelectAll: false
    }
});

When a row is being selected, specific actions can be performed if required. To learn how to specify them, refer to the Handling the Selection Event topic.

View Demo

Selecting in Code

DataGrid provides several methods with which to perform selection in code. If you have row keys, call the selectRows(keys, preserve) method passing them as the first argument. If you only have data objects, obtain the keys using the keyOf(obj) method and then call the selectRows(keys, preserve) method.

JavaScript
var key = dataGridInstance.keyOf(dataObject);
dataGridInstance.selectRows(key);
NOTE
Calling this method with one argument deselects previously selected records. If you need these records to remain selected, call this method with true as the second argument.

Additionally, you can select rows by their indexes using the selectRowsByIndexes(indexes) method.

JavaScript
dataGridInstance.selectRowsByIndexes([1, 8, 6]);

When row indexes are being calculated, data and group rows are counted, though only data rows can be selected. Refer to the Grid Rows article to get more information on how to calculate row indexes.

NOTE
Unlike selectRows(keys, preserve), the selectRowsByIndexes(indexes) method applies selection that will be cleared automatically once the current page is changed. Therefore, to preserve this selection, call this method within the onContentReady function.

If you need to select all rows in a grid, call the selectAll() method.

JavaScript
dataGridInstance.selectAll();

Selection can also be cleared in code by calling the clearSelection() method.

JavaScript
dataGridInstance.clearSelection();

If you need to deselect specific records, call the deselectRows(keys) method.

JavaScript
dataGridInstance.deselectRows([4, 6, 1]);

Setting Initial Selection

Rows can be selected not only at runtime, but also at design time. If you require certain rows to appear selected, declare an array of their keys and assign it to the selectedRowKeys option.

JavaScript
$("#gridContainer").dxDataGrid({
    // ...
    selectedRowKeys: [1, 5, 8]
});

Note that the specified selection mode does not affect the initial selection. Thus, you can specify multiple rows to be selected initially even if the selection mode is single.

Selecting Using Keyboard Shortcuts

In a multiple selection mode, a user can employ keyboard shortcuts to select rows. The following shortcuts are supported.

Shortcut Action
CTRL+Click Selects the clicked row.
SHIFT+Click Selects a range of rows.
CTRL+A Selects all rows. Make sure that the allowSelectAll option is true.
NOTE
On rare occasions, when virtual scrolling mode is used, selection made with SHIFT+Click may be reset. This is explained by the technical peculiarities of this mode. See the Vertical Scrolling article for more details.

For an overview of all key combinations presented in DataGrid, refer to the Keyboard Navigation article.

Handling the Selection Event

When one or several rows are being selected, the selectionChanged event fires. To handle it, implement a function and assign it to the onSelectionChanged option or bind it to the event using the on method. Within this function, you can specify performing actions if it is required by your scenario. When implementing the handling function, use information about selected and deselected rows. This information is accessible by using the fields of the object passed to this function. The following fields are available.

  • currentSelectedRowKeys
    Contains the keys of freshly selected rows.

  • currentDeselectedRowKeys
    Contains the keys of freshly deselected rows.

  • selectedRowKeys
    Contains the keys of all selected rows.

  • selectedRowsData
    Contains the data of all selected rows.

NOTE
If a field providing key values is not specified in a data source, the whole data object is considered key for a grid record. In this case, all arrays passed to the selectionChanged handler contain data objects instead of keys.

Additionally, you can obtain the keys or data objects of selected rows outside the selectionChanged handler at any point of the lifetime of your application. For this purpose, use the getSelectedRowKeys() and getSelectedRowsData() methods.