Keyboard 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 to the selection up, down, left and right. If the selected 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. User ctrl + left and right to move to start and end of the line.

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.

Groups

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.

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 Selection

If you want keyboard navigation turned off, then set suppressCellSelection=true in the gridOptions.

Example

All the items above (navigation, editing, groups, selection) are observable in the test drive. As such, a separate example is not provided here.

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 - 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 two methods: navigateToNextCell and tabToNextCell.

navigateToNextCell

Provide a callback navigateToNextCell if you want to override the arrow key navigation. The function signature is as follows:

interface NavigateToNextCellParams { // the keycode for the arrow key pressed, left = 37, up = 38, right = 39, down = 40 key: number; // the cell that currently has focus previousCellPosition: CellPosition; // the cell the grid would normally pick as the next cell for this navigation nextCellPosition: CellPosition; event: KeyboardEvent; }

tabToNextCell

Provide a callback tabToNextCell if you want to override the tab key navigation. The parameter object is as follows:

interface TabToNextCellParams { // true if the shift key is also down backwards: boolean; // true if the current cell is editing (you may want to skip cells that are not editable, // as the grid will enter the next cell in editing mode also if tabbing) editing: boolean; // the cell that currently has focus previousCellPosition: CellPosition; // the cell the grid would normally pick as the next cell for this navigation nextCellPosition: CellPosition; }

CellPosition

Both functions above use CellPosition. This is an object that represents a cell in the grid. Its interface is as follows:

interface CellPosition { // either 'top', 'bottom' or undefined/null (for not pinned) rowPinned: string; // a positive number from 0 to n, where n is the last row the grid is rendering rowIndex: number; // the grid column column: Column; }

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.

Example Custom Navigation

The example below shows both navigateToNextCell and 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 it may be useful to tab into grid from another element or user action such as a button click.

This can be achieved by using a combination of DOM event listeners and Grid API calls shown in the following code snippet:

// obtain reference to input element var myInput = document.getElementById("my-input"); // intercept key strokes within input element myInput.addEventListener("keydown", function (event) { // code for tab key var tabKeyCode = 9; // ignore non tab key strokes if(event.keyCode !== tabKeyCode) return; // prevents tabbing into the url section event.preventDefault(); // scrolls to the first row gridOptions.api.ensureIndexVisible(0); // scrolls to the first column var firstCol = gridOptions.columnApi.getAllDisplayedColumns()[0]; gridOptions.api.ensureColumnVisible(firstCol); // sets focus into the first grid cell gridOptions.api.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 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 input will cause the grid to navigate to the first cell.

Keyboard Events

It is possible to add custom behaviour to any key event that you want using the grid events cellKeyPress (gets called when a DOM keyPress event fires on a cell) and 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 cellKeyPress or 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. This is achieved through the cellKeyPress listener.

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:

function suppressKeyboardEvent(params: SuppressKeyboardEventParams) => boolean; export interface SuppressKeyboardEventParams extends IsColumnFuncParams { // the keyboard event the grid received. inspect this to see what key was pressed event: KeyboardEvent; // whether the cell is editing or not. sometimes you might want to suppress event // only when cell is editing. editing: boolean; node: RowNode; // row node data: any; // row data column: Column; // column colDef: ColDef; // column definition context: any; // context object api: GridApi | null | undefined; // grid API columnApi: ColumnApi | null | undefined; // column API }

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.