JavaScript Data GridKeyboard Interaction
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.
Navigation
Use the arrow keys (← ↑ → ↓) to move focus up, down, left and right. If the focused cell is already on the boundary for that position (e.g. if on the first column and the left key is pressed) then the key press has no effect. Use ^ Ctrl+← to move to the start of the line, and ^ Ctrl+→ to move to the end.
If a cell on the first grid row is focused and you press ↑, 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 then 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.
When a header cell is focused, commands like Page Up, Page Down, Home, End, ^ Ctrl+←/→ will not work as they do when a grid cell is focused.
Groups
If on a group element, hitting the ↵ Enter key will expand or collapse the group.
Editing
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.
Selection
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 Focus
If you want keyboard navigation turned off, then set suppressCellFocus=true
in the gridOptions.
Column Header Navigation
The grid header supports full keyboard navigation, however the behaviour may differ based on the type of Column Header that is currently focused.
Column Headers can be:
- Moved by pressing ⇧ Shift + ← / →.
- Resized by pressing ⌥ Alt + ← / →.
Column Group Headers
While navigating Column Groups Headers, if the current Column Group is expandable, pressing ↵ Enter will toggle the expanded state of the group.
Normal Column Headers
Regular Column Headers may have selection checkboxes, sorting functions and menus, so to access all these functions while focusing a Column Header, you can do the following:
- Press ␣ Space to toggle the Column Header checkbox selection.
- Press ↵ Enter to toggle the sorting state of that column.
- Press ⇧ Shift+↵ Enter to toggle multi-sort for that column.
- Press ^ Ctrl+↵ Enter to open the menu for the focused Column Header.
- When a menu is open, simply press ⎋ Esc to close it and the focus will return to the Column Header.
Floating Filter Headers
While navigating the Floating Filter Columns Headers with the keyboard, pressing ← → will move focus from one Column Header to the next. If you wish to navigate within the Floating Filter Cell, press ↵ Enter to focus the first enabled element within the current Floating Filter Cell, and press ⎋ Esc to return focus to the Floating Filter Column Header.
Example
The example below has grouped headers, headers and floating filters to demonstrate the features mentioned above:
Custom Navigation
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 (e.g. you may want the ⇥ Tab key to navigate to the cell below, not the cell to the right). To facilitate this, the grid offers four methods: navigateToNextCell
, tabToNextCell
, navigateToNextHeader
and tabToNextHeader
.
navigateToNextCell
Provide a callback navigateToNextCell
if you want to override the arrow key navigation.
tabToNextCell
Provide a callback tabToNextCell
if you want to override the ⇥ Tab key navigation.
CellPosition
Both functions above use CellPosition
. This is an object that represents a cell in the grid.
Properties available on the CellPosition
interface.
columnTypeColumn | The grid column |
row | A positive number from 0 to n, where n is the last row the grid is rendering or -1 if you want to navigate to the grid header |
row | Either 'top', 'bottom' or null/undefined (for not pinned) |
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 nextCellPosition
to stick with the grid default behaviour. Return null
/undefined
to skip the navigation.
navigateToNextHeader
Provide a callback navigateToNextHeader
if you want to override the arrow key navigation.
tabToNextHeader
Provide a callback tabToNextHeader
if you want to override the ⇥ Tab key navigation.
HeaderPosition
Both navigateToNextHeader
and tabToNextHeader
use HeaderPosition
. This is an object that represents a header in the grid.
You should return the HeaderPosition
you want in the navigateToNextHeader
and tabToNextHeader
functions to have it focused. Returning null
or undefined
in navigateToNextHeader
will do nothing (same as focusing the current focused cell), however, doing the same thing in tabToNextHeader
will allow the browser default behaviour for ⇥ Tab to happen. This is useful for tabbing outside of the grid from the last cell or ⇧ Shift tabbing out of the grid from the first cell.
The navigateToNextCell
and tabToNextCell
are only called while navigating across grid cells, while
navigateToNextHeader
and tabToNextHeader
are only called while navigating across grid headers.
If you need to navigate from one container to another, pass rowIndex: -1
in CellPosition
or headerRowIndex: -1
in HeaderPosition
.
Example Custom Cell Navigation
The example below shows how to use navigateToNextCell
, tabToNextCell
, navigateToNextHeader
and tabToNextHeader
in practice.
Note the following:
navigateToNextCell
swaps the up and down arrow keys.tabToNextCell
uses tabbing to go up and down rather than right and left.navigateToNextHeader
swaps the up and down arrow keys.tabToNextHeader
uses tabbing to go up and down rather than right and left.- When a cell in the first grid row is focused, pressing the down arrow will navigate to the header by passing
rowIndex: -1
. - When a header cell in the last header row is focused, pressing the up arrow will navigate to the first grid row by passing
headerRowIndex: -1
. - Tabbing/Shift tabbing will move the focus until the first header or the last grid row, but focus will not leave the grid.
Custom Master Detail Navigation
Master Detail Grids grids can contain Custom Details that have their own renderer and hence will need to implement its own keyboard navigation. An example of this can be seen in the Custom Details Keyboard Navigation Example.
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 behaviour 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:
// obtain reference to input element
const myInput = document.getElementById("my-input");
// intercept key strokes within input element
myInput.addEventListener("keydown", event => {
// ignore non tab key strokes
if(event.key !== 'Tab') return;
// prevents tabbing into the url section
event.preventDefault();
// scrolls to the first row
gridApi.ensureIndexVisible(0);
// scrolls to the first column
const firstCol = api.getAllDisplayedColumns()[0];
gridApi.ensureColumnVisible(firstCol);
// sets focus into the first grid cell
gridApi.setFocusedCell(0, firstCol);
}, true);
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 behaviour 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 behaviour, 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...).
Keyboard Events
It is possible to add custom behaviour to any key event that you want using the grid events cellKeyDown
(gets called when a DOM keyDown
event fires on a cell).
These keyboard events are monitored by the grid panel, so they will not be fired
when the keydown
happens inside of a popup editor, as popup elements are
rendered in a different DOM tree.
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
cellKeyDown
is fired, the details of the event are logged to the console. - When the user hits S on a row, the row selection is toggled.
Suppress Keyboard Events
It is possible to stop the grid acting on particular events. To do this implement colDef.suppressHeaderKeyboardEvent
and/or colDef.suppressKeyboardEvent
callback. The callback should return true
if the grid should suppress the events, or false
to continue as normal.
suppressHeaderKeyboardEvent
suppressKeyboardEvent
The callback is available as a column callback (set on the column definition). If you want it to apply to all columns then apply to the defaultColDef
property.
Example: Suppress Keyboard Navigation
The example below demonstrates suppressing the following keyboard events:
- On the Athlete column cells only:
- ↵ Enter will not start or stop editing.
- On the Country column cells only:
- ↑ ↓ arrow keys are allowed. This is the only column that allows navigation from the grid to the header.
- On all cells (including the cells of the Athlete Column):
- ^ 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.
- On the Country header only:
- Navigation is blocked from the left to right using arrows but is allowed using ⇥ Tab.
- Navigation up and down is allowed. This is the only header that allows navigation from the header to the grid cells.
- ↵ Enter is blocked. This is the only header that blocks sorting / opening menu via keyboard.
- On all headers (excluding country):
- Navigation is blocked up and down, but navigation left / right is allowed using arrows and ⇥ Tab.