Keyboard Navigation

Clicking on a cell gives the cell focus. You can then navigate and interact with the grid in the following ways:

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.

Custom Actions

Custom cell renderers can listen to key presses on the focused div. The grid element that receives the focus is provided to the cell renderers via the eGridCell parameter. You can add your own listeners to this cell. Via this method you can listen to any key press and do your own action on the cell eg hitting 'x' may execute a command in your application for that cell.

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 previousCellDef: GridCellDef; // the cell the grid would normally pick as the next cell for this navigation nextCellDef: GridCellDef; }

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 previousCellDef: GridCellDef; // the cell the grid would normally pick as the next cell for this navigation nextCellDef: GridCellDef; }

GridCellDef

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

interface GridCellDef { // either 'top', 'bottom' or undefined/null (for not floating) floating: 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 GridCellDef for current and next cells, as well as returning a GridCellDef object. The returned GridCellDef will be the one the grid puts focus on next. Return the provided nextCellDef 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.