Keyboard and accessibility
The active cell, the APG grid keys, a roving tab stop and ARIA, and how to replace any key without leaving the grid behind.
Install navigation
The keys are a feature: navigation(), from the /navigation entry.
It gives the grid an active cell, the keys below, one tab stop and the APG grid's roles.
import { navigation } from "@fragiola/data-grid-react/navigation";
const features = [navigation()];
<DataGrid.Root features={features} columns={columns} rows={people}>
{/* … */}
</DataGrid.Root>Without it, the grid is a table, the APG table pattern: role="table", its rows row, its
header cells columnheader and its cells cell. No cell is ever active, neither the grid nor its
cells are tab stops (the controls inside cells keep their own tab order), and the arrows are the
page's. It still renders, scrolls and virtualizes the same. The selections, the clipboard and the
fill handle build on the active cell: cell ranges need
navigation() installed.
The active cell
One cell at a time is active: it has data-active and is the grid's tab stop. Its props
are navigation's: activePosition with onActivePositionChange, or defaultActivePosition. The keys move
it, the grid scrolls it into view and focuses it.
The active cell stays active when focus leaves the grid, so Tab comes back to it. To draw it only
while it has focus, as the examples do, pair the two: [data-active]:focus-within (Tailwind:
data-active:focus-within:).
| key | moves to |
|---|---|
| Arrows | the next cell in that direction (header rows are -1 and above), through the summary rows as they show |
| Home, End | the row's first or last cell |
| Ctrl+Home, Ctrl+End | the grid's first or last cell (a bottom summary row's, with some) |
| PageUp, PageDown | a page of rows up or down, in the body |
| Tab | leaves the grid |
| Shift+Space | selects the active row, or clears it (row selection installed and on) |
| Shift+↑, Shift+↓ | the next row, selecting from the anchor (many rows selectable) |
| Ctrl+A, ⌘+A | selects every row (many rows selectable) |
| Shift+arrows, Shift+Home, Shift+End, Shift+PageUp, Shift+PageDown | move the selected range's focus, the active cell staying its anchor (cell selection installed and on; then Shift+↑, Shift+↓ and Ctrl+A are the cells', Shift+Space stays the row's) |
| Ctrl+Shift+Home, Ctrl+Shift+End | take the range's focus to the first or the last cell (cell selection on) |
| Ctrl+A, ⌘+A | selects every body cell (cell selection on) |
| Escape | clears the selected range; a plain move clears it too |
| Escape | with nothing else to end (no range, edit, drag or controls), focus leaves the grid: the active cell stays, and Tab comes back to it. In a grid nested in a cell, focus goes to that cell. The key is not prevented, so a dialog around the grid still closes |
| Ctrl+C, Ctrl+V | copy the range (or the active cell) as tab-separated text, paste into it (clipboard() installed, cell selection on; ⌘ on a Mac) |
| Enter, F2, a printable key | on an editable cell, edit it (the printable key starts the editor; a character typed with AltGr or Option too) |
| Enter, Shift+Enter, Tab, Shift+Tab | in an edit, commit it and move down, up, to the next or the previous column |
| Escape | in an edit, cancel it, focus back on the cell; during a fill's drag, cancel it |
| Ctrl+Shift+←, Ctrl+Shift+→ | moves a reorderable header cell's column or group, the active cell following it (columnReorder() installed; ⌘ on a Mac) |
| Ctrl+Shift+↑, Ctrl+Shift+↓ | moves the active cell's row up or down, the active cell following it (row reordering on; ⌘ on a Mac) |
| Enter, Space | on a group row, expands or collapses it (row grouping); Space on a tree's parent too (tree data) |
| →, ← | on a row's tree cell in a treegrid (the one holding its toggle), expands a collapsed group, collapses an expanded one, or goes to the row it is under |
Moves stop at the edges. In a right-to-left grid the arrows
mirror: ← moves to the next column and → to the previous one, as they point; Home and End stay the
row's first and last cell, Ctrl+Shift+← moves a header cell after its next sibling, and on a resize
handle ← moves it to the left, which widens its column. A click or a Tab into a cell makes it active. With
sorting installed, Enter and Space on a sortable column's header cell
toggle its sort (Ctrl adds the column).
On a reorderable header cell, Ctrl+Shift+← and Ctrl+Shift+→
move its column (or group) before the previous sibling or after the next one, focus staying on
it; elsewhere they move the active cell as the arrows do. While the rows
move, Ctrl+Shift+↑ and Ctrl+Shift+↓ on a body cell move its row
by one, once per press, focus following it once you have moved it (with a rowKey; nothing moves
while the grid is sorted); the same right to left.
With column groups, the header has several rows: Up from a column reaches the group above it, Down from a group its first column in view, and Left and Right move across the cells of a header row. A cell spanning columns is one cell to the keys: an arrow into a column it covers lands on it, and the arrows leaving it go to the column past its span. The summary rows are rows to the keys: Up from the first body row reaches the top ones, Down from the last the bottom ones.
With row groups the grid is a treegrid and the keys are the APG
treegrid's: Enter and Space on a group row toggle it (F2 hands its controls the keys), Space a
tree's parent, and on a row's tree cell (the one holding its toggle; for a row with none, the
column the toggles are in, else the first) → expands a collapsed group (then moves, as anywhere
else), ← collapses an expanded one, else goes to the row it is under. Shift+Space on a group row
selects its rows.
One tab stop
With navigation installed: while no cell is active, the grid is the tab stop; focusing it activates the first cell in view.
Then the active cell is (tabIndex 0, the others -1), so Tab moves past the grid in one step.
The controls inside cells (buttons, links, fields, a select, a box to check) are no stops of their
own (without navigation, they are: the grid leaves them alone): the grid keeps them at tabIndex -1, the ones your cells render later included, so a grid
full of controls is still one stop. A grid nested in another one's cell is reachable through
that cell: its stop is in the tab order only while the outer active cell holds it
(Nested grids).
Controls in cells
A cell's controls take the keys in interaction, the grid's other mode beside navigation:
| key | in navigation | in interaction |
|---|---|---|
| Enter, F2 | the active cell's controls take the keys, the first takes focus | the control's |
| Tab, Shift+Tab | leave the grid | the cell's next or previous control, round and round |
| Escape | — | back to navigation, focus on the cell |
| Arrows, Home, End… | move the active cell | the control's (a field's caret, a select's options) |
A click on a control does what Enter does: its cell becomes active and its controls take the keys.
Focus leaving the cell (a click elsewhere, a menu portalled out of it) goes back to navigation. On
a sortable column's header cell (sorting installed), Enter sorts, and F2 reaches its controls. A cell in interaction
carries data-interacting, and useCell and useHeaderCell report interacting.
A control you want to stay a tab stop of its own carries data-grid-tab-stop: the grid leaves its
tabIndex alone. From code, engine.run("interact-cell", { rowIndex, columnIndex }) and
engine.run("leave-cell", {}) do what Enter and Escape do, and engine.get("interaction") tells
which cell is in interaction.
Resize handles
A column's resize handle (columnResize() installed) is a control of its header cell: F2
(or Enter, where the header does not sort) hands it the keys, or Tab reaches it among the cell's
other controls. Then, on the focused handle:
| key | does |
|---|---|
| ←, → | moves the handle 10 px its way: the column wider where it grows that way (to the right, or to the left right to left; toward the start for a column pinned at the end) |
| Shift+←, Shift+→ | the same by 50 px |
| Home, End | the column's minimum, its maximum (its aria-valuemax: the view's width, without a maxWidth) |
| Enter | fits the column to its content (Automatic widths) |
| Escape | back to navigation; the width stays |
The other page keys and Space do nothing on a handle: the grid's container never pages under it. Escape also cancels a drag, putting back the width it started from.
Whose key it is
The grid takes keys pressed on its cells, on the grid itself and on its scroll container; in
interaction, only Escape and Tab from the cell's controls. A key pressed on your own content beside
the cells, such as a button in DataGrid.Empty or anything in a
row's detail, or in a menu portalled out of a cell, stays with
that content. The arrows move between rows' cells and never land in a detail.
Replacing a key
A cell's onKeyDown runs before the grid's: preventDefault cancels the grid's handling, and
useDataGrid<Person, typeof features>().model.run("active-position.set", …) (a key of
navigation's, typed with it) moves the cell where you want. The
custom-navigation example makes Tab move across rows this way.
A middleware can refuse or rewrite any move:
import { veto } from "@fragiola/data-grid-react";
// ArrowUp from the first row stays there: the header never becomes active
model.use((ctx, next) =>
ctx.command === "active-position.move" &&
ctx.payload.direction === "up" &&
ctx.state.activePosition?.rowIndex === 0
? veto("the header is not navigable")
: next(),
);ARIA
With navigation, the grid is role="grid" (treegrid with row groups; without it table) with aria-rowcount and aria-colcount counting every row and column,
rendered or not; rows and cells carry aria-rowindex and aria-colindex. Name the grid with
aria-label: the package sets no names. See State attributes.