The grid responds to keyboard interactions from the user as well as emitting events when key presses happen on the grid cells. Below shows all the keyboards interactions that can be done with the grid.
Use the arrow keys to move focus up, down, left and right. If the focused cell is already on the boundary for that position (eg if on the first column and the left key is pressed) then the key press has no effect. Use ctrl + left and right to move to start and end of the line.
If a cell on the first grid row is focused and you you press
arrow up, the focus will be moved into
the grid header.
The header navigation focus navigation works the same as the grid's, arrows will move up/down/left/right, tab will
move the focus horizontally until the last header cell and the move on to the next row.
Use page up and page down to move the scroll up and down by one page. Use home and end to go to the first and last rows.
If using grouping and
groupUseEntireRow=true, then the group row is not focusable. When
navigating, the grouping row is skipped.
If on a group element, hitting the enter key will expand or collapse the group. This only works
when displaying groups in a column (
groupUseEntireRow=false), as otherwise the group cell
is not selectable.
Pressing the enter key on a cell will put the cell into edit mode, if editing is allowed on the cell. This will work for the default cell editor.
Pressing the space key on a cell will select the cells row, or deselect the row if already selected. If multi-select is enabled, then the selection will not remove any previous selections.
Suppress Cell Selection
If you want keyboard navigation turned off, then set
suppressCellSelection=true in the
The grid header is supports full keyboard navigation, however, the behaviour my differ based on the type of header is currently focused.
While navigating grouped headers, if the current grouped header is expandable, pressing
will toggle the expanded state of the group
Regular header may have selection checkboxes, sorting functions and menus, so to access all these functions while focusing a header, you can do the following:
SPACEto toggle the header checkbox selection.
ENTERto toggle the sorting state of that column.
Shift + ENTERto toggle multi-sort for that column.
Ctrl/Cmd + ENTERto open the menu for the focused header.
When a menu is open, simply press
ESCAPEto close it and the focus will return to the header.
While navigation the floating filters header with the keyboard pressing left/right the focus will move
from header cell to header cell, if you wish to navigate within the cell, press
ENTER to focus
the first enabled element within the current floating filter cell, and press
ESCAPE to return
the focus to the floating filter cell.
The example below has grouped headers, headers and floating filters to demonstrate the features mentioned above:
Most people will be happy with the default navigation the grid does when you use the arrow keys
and the tab key. Some people will want to override this - for example maybe you want the tab key
to navigate to the cell below, not the cell to the right. To facilitate this, the grid offers
Provide a callback
navigateToNextCell if you want to override the arrow key navigation. The
function signature is as follows:
Provide a callback
tabToNextCell if you want to override the tab key navigation. The
parameter object is as follows:
Both functions above use CellPosition. This is an object that represents a cell in the grid. Its interface is as follows:
The functions take a CellPosition for current and next cells, as well as returning a CellPosition object.
The returned CellPosition will be the one the grid puts focus on next. Return the provided
to stick with the grid default behaviour. Return null/undefined to skip the navigation.
tabToNextCellmethods are not called while using the keyboard to navigate within the grid header. If you need to navigate into the grid header, you can pass rowIndex: -1, but once focus is within the header, the standard keyboard navigation will take place.
Example Custom Navigation
The example below shows both
tabToNextCell in practice.
navigateToNextCell swaps the up and down arrow keys.
tabToNextCell uses tabbing
to go up and down rather than right and left.
Tabbing into the Grid
In applications where the grid is embedded into a larger page, by default, when tabbing into the grid, the first column header will be focused.
You could override this behavior to focus the first grid cell, if that is a preferred scenario using a combination of DOM event listeners and Grid API calls shown in the following code snippet:
Example: Tabbing into the Grid
In the following example there is an input box provided to test tabbing into the grid. Notice the following:
- Tabbing out of the first input box will gain focus on the first grid cell.
- When the first cell is out of view due to either scrolling down (rows) or across (columns), tabbing out of the first input will cause the grid to navigate to the first cell.
- Tabbing out of the second input box will have the default behavior which is to focus the first grid header.
- When the first header is out of view due to horizontal scroll, tabbing into the grid will cause the grid to scroll to focus the first header.
- Shift-Tabbing out third input (below the grid) will have the default focus behavior, which is to focus the last element of the grid. This element will vary depending on how many features have been enabled (eg. Row Pagination, Tool Panels, etc...).
It is possible to add custom behaviour to any key event that you want using the grid
cellKeyPress (gets called when a DOM keyPress event fires on a cell)
cellKeyDown (gets called when a DOM keyDown event fires on a cell).
The grid events wrap the DOM events and provides additional information such as row and column details.
The example below shows processing grid cell keyboard events. The following can be noted:
Each time a
cellKeyDownis fired, the details of the event are logged to the console.
When the user hits 's' on a row, the row selection is toggled. This is achieved
Suppress Grid Keyboard Events
It is possible to stop the grid acting on particular events. To do this implement
suppressKeyboardEvent callback. The callback should return true if the
grid should suppress the events, or false to continue as normal.
The callback has the following signature:
The callback is available as a grid callback (gets called regardless of what cell the keyboard event is on) and as a column callback (set on the column definition and gets called only for that column). If you provide the callback on both the grid and column definition, then if either return 'true' the event will be suppressed.
The example below demonstrates suppressing the following keyboard events:
- On the Athlete column only:
Enter will not start or stop editing.
- On all columns:
- Ctrl & A will not select all cells into a range.
- Ctrl & C will not copy to clipboard.
- Ctrl & V will not paste from clipboard.
- Ctrl & D will not copy range down.
- Page Up and Page Down will not get handled by the grid.
- Home will not focus top left cell.
- End will not focus bottom right cell.
- ← ↑ → ↓ Arrow keys will not navigate focused cell.
- F2 will not start editing.
- Delete will not start editing.
- Backspace will not start editing.
- Escape will not cancel editing.
- Space will not select current row.
- Tab will not be handled by the grid.