# Grid navigation

> Moving the active cell through a grid by the keyboard, to its neighbours and to its edges.

In a grid, the keyboard moves the active cell in two directions, and reaches the
far edges of data too large to see at once.

## Best practices

**Move one cell with each arrow key**, in the direction of the arrow. Where text
reads right to left, Left and Right are mirrored with the columns.

**Reach the edges directly.** Home and End go to the first and last cell of the
row. With the command key, an arrow goes to the edge in its direction, and Home
and End to the first and last cells of the whole grid.

**Move by the page.** Page Up and Page Down move by the rows in view, so two
presses never skip rows and never repeat them.

**Keep the active cell in view.** When a move lands on a cell outside the view,
scroll by the least that shows it.

**Stop at the edges.** A move past the first or last row or column stays where
it is; a grid does not wrap.

**Make the grid one stop in the Tab sequence.** Tab enters the grid at its active
cell and leaves it again; the arrow keys move within. While a cell is being
edited, Tab commits it and moves to the next cell, as people filling in a row
expect.

## Keys

| Key                       | Moves the active cell                     |
| ------------------------- | ----------------------------------------- |
| Arrow keys                | One cell                                  |
| Command with an arrow key | To the edge of the grid in that direction |
| Home, End                 | To the first or last cell of the row      |
| Command-Home, Command-End | To the first or last cell of the grid     |
| Page Up, Page Down        | By the rows in view                       |

See also [Keyboard navigation](https://ui.publictheta.com/foundations/navigation.md) and [Cell selection](https://ui.publictheta.com/foundations/grid-selection.md).

## Behaviour

Each statement is verified by a test in Chromium, Chromium (touch), Firefox, WebKit, WebKit (touch), unless it names the environments it applies to or is marked open.
- Arrow keys move one cell.
- Left and right are mirrored where text reads right to left.
- With the command key, an arrow goes to the edge of the grid.
- Home and End go to the ends of the row.
- With the command key, Home and End go to the first and last cells of the grid.
- Page Up and Page Down move by the rows in view.
- No move leaves the grid.
- Other keys are not moves.

## Reference implementation

React: `npx shadcn@latest add https://ui.publictheta.com/r/grid-navigation.json`