Top
DataGrid - Selection and keyboard navigation
DataGrid
The <DataGrid /> offers a rich selection-related functionality together with keyboard navigation. You can use single selection or multiple selection, row or cell selection. In this section we'll be explaining all of these features with examples to help you understand how to configure the <DataGrid /> to support all those scenarios.
Let's start with a simple example without support for selection. Try clicking the <DataGrid /> below and then navigate with up/down keyboard arrows. Notice the currently active row changes as you hit arrow up/down. By default keyboard navigation is enabled, but you can turn it off by specifying enableKeyboardNavigation=false. You can also use home/end or page up/down to navigate the <DataGrid /> rows. Additionally, when you move your mouse over a <DataGrid /> row, it shows a hover state (this can be disabled by using showHoverRows=false).
Use activeIndex (controlled) or defaultActiveIndex (uncontrolled), combined with onActiveIndexChange to have full control on user navigation and the currently active row in the <DataGrid />.
When using the controlled activeIndex prop and onActiveIndexChange callback prop to update the activeIndex, if you're doing other compute intensive stuff on the render function, you might notice some performance degradation in the scenario when the user keeps arrow up/down key pressed to quickly navigate to other records. If this is the case, it's better to use the uncontrolled defaultActiveIndex prop instead to obtain better performance.
When navigating the <DataGrid /> with keyboard navigation, as the active index is updated, the <DataGrid /> is automatically scrolled to show the currently active row in the viewport.
In the example above you can use keyboard navigation and then hit the Enter key to perform the selection. If toggleRowSelectOnClick=true, hitting the Enter key again deselects the selected row. You can also use mouse click to select, and ctrl/cmd+click to deselect. onSelectionChange notifies you when the selection has changed.
enableSelection enables the selection on the <DataGrid /> - NOTE: this is uncontrolled selection, without any default selected values. For controlled selection, use selected. For uncontrolled selection where you want to specify a default selection, use defaultSelected.
Using controlled selection gives you a lot of flexibility like preventing certain rows from being selected, preventing row deselection on ctrl/cmd + click, etc.
Browser text selection is disabled by default, since columnUserSelect=false. See columnUserSelect for details.
Single selection is certainly useful, but there are a lot more cases when you want multiple selection. The <DataGrid /> supports very powerful multi-selection, including selection via a checkbox column. Let's start with a basic multi-select example.
You can use click, ctrl/cmd + click or shift + click just like in OS file-system explorers (Finder in macOS or Explorer in Windows) - so the same patterns people are already used-to are used by the <DataGrid />.
For enabling uncontrolled multiselection, use enableSelection=true and multiSelect=true.
However, you can also only specify defaultSelected={} (use an object as a value) to have uncontrolled multiple selection. To specify some records should be selected by default, you can use defaultSelected={ 1: true, 5: true } - in this case, the items with the value of the idProperty equal to 1 and equal to 5 will be selected by default. See the example below for a demo.
When the user interacts with the <DataGrid /> and changes the current selection, onSelectionChange is called with an object, that has a data property (an array that holds all the selected items) and a selected property (an object with the selected items, keyed using their id properties as specified by idProperty).
To specify default multiple selection (either controlled or uncontrolled), you need to specify an object with the keys being the ids of the items to render as selected, and values to be truthy values (eg: {5: true, 10: true} for the selected or defaultSelected respectively. If you specify a string or a numeric value, the <DataGrid />assumes single selection.
Multiple selection can also be used with a checkbox column. Specify checkboxColumn and a checkbox column will be displayed as the first column of the grid and will be used for multiple selection.
By specifying checkboxColumn=true the default checkbox column is rendered. Use checkboxColumn={... column config ...} to customize the appearance of the checkbox column and control any part of the rendering, just like you do for normal columns.
In the example above, try grouping by permissionToCall, then try sorting by the grouped column. You can use keyboard navigation to collapse/expand group rows.
Besides row selection, the <DataGrid /> also supports cell (single/multiple) selection + keyboard cell navigation. In order to enable cell selection, either specify the uncontrolled defaultCellSelection=[] prop or the controlled cellSelection=[] prop.
By default cell selection is multiple. If you want to enable single cell selection, specify multiSelect=false.
The cell selection value is an array of strings - each string representing a cell. The string for each cell is the value of the idProperty for that row, followed by a comma, followed by the name/id of corresponding column: <idProperty value>,<column id or name>.
Try and select a few cells in the grid above, then sort the grid by the age column and see selected cells remaining appropriately selected even after the sort. This is because the idProperty is used in the value for each selected cell.
You can use the little square at the bottom-right border of the active cell to drag and extend the current cell selection.
When selectOnDrag is enabled you can hold the mouse down on a cell and drag to another cell to create multiple cell selection.