Documentation
Concepts

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.

people.tsx
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:).

keymoves to
Arrowsthe next cell in that direction (header rows are -1 and above), through the summary rows as they show
Home, Endthe row's first or last cell
Ctrl+Home, Ctrl+Endthe grid's first or last cell (a bottom summary row's, with some)
PageUp, PageDowna page of rows up or down, in the body
Tableaves the grid
Shift+Spaceselects 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, ⌘+Aselects every row (many rows selectable)
Shift+arrows, Shift+Home, Shift+End, Shift+PageUp, Shift+PageDownmove 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+Endtake the range's focus to the first or the last cell (cell selection on)
Ctrl+A, ⌘+Aselects every body cell (cell selection on)
Escapeclears the selected range; a plain move clears it too
Escapewith 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+Vcopy 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 keyon an editable cell, edit it (the printable key starts the editor; a character typed with AltGr or Option too)
Enter, Shift+Enter, Tab, Shift+Tabin an edit, commit it and move down, up, to the next or the previous column
Escapein 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, Spaceon 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.

Keyboard navigation
Gallery

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:

keyin navigationin interaction
Enter, F2the active cell's controls take the keys, the first takes focusthe control's
Tab, Shift+Tableave the gridthe cell's next or previous control, round and round
Escape—back to navigation, focus on the cell
Arrows, Home, End…move the active cellthe 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.

Interactive cells
Gallery

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:

keydoes
←, →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, Endthe column's minimum, its maximum (its aria-valuemax: the view's width, without a maxWidth)
Enterfits the column to its content (Automatic widths)
Escapeback 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:

no-header.ts
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.