Accessibility

Conformance target

The target is WCAG 2.1 AA. No conformance audit has been performed against gridcn.

What the grid implements

Grid semantics

The scroll root carries role="grid". Each rendered row carries role="row". Each data cell carries role="gridcell". Each header cell carries role="columnheader".

The aria index and count model

aria-rowcount and aria-colcount sit on the grid root. aria-rowindex sits on each row. aria-colindex sits on each cell and header cell. Counts and indices are all 1-based, per the WAI-ARIA grid pattern.

The row index layout accounts for the header and both pinned-row bands, in this order:

aria-rowcount on the grid root always includes both pinned bands, so a screen reader announces the true total row count, not just the data row count.

The marker column (row numbers or checkboxes) sits outside this index space entirely. It carries no aria-colindex, and no data column's aria-colindex shifts to make room for it. aria-colcount counts only real data columns.

Roving tabindex

The grid follows the WAI-ARIA APG roving-tabindex pattern for a single active cell. Before any cell becomes active, the grid root itself is the one tabbable entry point (tabIndex={0}). Once a cell becomes active, that cell alone carries tabIndex={0}, every other cell carries tabIndex={-1}, and the root reverts to tabIndex={-1}. Real DOM focus follows the active cell, including when it scrolls out of the rendered window and back in. Focus never gets lost.

Pinned rows and skeleton (not-yet-loaded) cells carry no tabindex at all. They sit outside roving-tabindex navigation, since neither is ever the active cell.

Selection announcement model

Every selected cell carries aria-selected="true", for a single cell, a range, a row-channel, or a column-channel selection alike. aria-multiselectable on the grid root reflects whether more than one cell can be selected at once, true whenever any multi-cell selection channel (range, row, column, or multi-range) is enabled.

Selection paint goes through an overlay layer. Membership changes update aria-selected on the affected cells (a bounded, guarded re-render — see Performance /docs/performance for the invariant wording). The aria-selected attribute is the accessibility-tree signal a screen reader reads; the overlay is the sighted-user visual signal. The two agree on the same state.

Editor focus behavior

Opening a cell editor renders a real <input> (or other native control) inside the gridcell, so assistive tech reads it as an ordinary form field. Closing the editor (commit or cancel) returns DOM focus to the cell itself. Focus never lands on document.body or gets dropped.

aria-busy and loading

Three separate elements carry aria-busy or an equivalent progress role:

• The grid root carries aria-busy="true" while the loading prop is true.
• A skeleton row, rendered when loading is true and there are zero rows yet, carries aria-busy="true" per row, plus role="presentation" and an aria-label (from labels.grid.loading) on the skeleton block as a whole.
• A background refresh (loading true with rows already present) shows a slim progress bar instead, role="progressbar" with an aria-label and matching aria-valuetext.

Toolbar and sort-list live regions

The data-grid-toolbar search box announces its match count through role="status" with aria-live="polite". The data-grid-toolbar filter popover and the data-grid-sort-list popover each carry a role="status" aria-live="polite" region that announces every reorder, for example "Name filter moved to position 2 of 3" or "Age sort moved to position 1 of 2" (labels.toolbar.filterReorderAnnouncement / labels.sort.sortReorderAnnouncement).

Reordering itself is fully keyboard-operable. Each row's drag grip is focusable. A plain ArrowUp or ArrowDown on a focused grip moves that row exactly one position, and always wins over @dnd-kit/react's own keyboard-drag gesture on the same key. Focus stays on the moved row's grip after a reorder, and moves to the next row's grip (or the "Add filter"/"Add sort" button once the list is empty) after a delete. See Sorting, filtering & search for the full per-key table for both popovers.

Keyboard coverage

Selection & keyboard is the canonical shortcut reference for cell navigation, selection, and editing. This page does not repeat that table.

Test status matrix

What the automated Chromium suite verifies, area by area.

Known gaps

• The fill handle is mouse-only and hidden from assistive tech. Dragging it has no keyboard equivalent. Keyboard users get the same result with Ctrl/Cmd+D (fill down) or Ctrl/Cmd+R (fill right). See Fill handle.
• Pinned rows are not keyboard-navigable and not in the selection model. Arrow keys, Tab, and Ctrl+Arrow jumps move only within data rows. A pinned row is never the active cell, carries no tabindex, and carries no aria-selected. See Pinned rows.
• The grid renders no page landmark of its own. Place it inside <main> or a labeled <section> yourself. Without a surrounding landmark, screen-reader region navigation, and axe's own region rule, cannot see the grid as part of a labeled page region. The automated suite's own fixture wraps the grid in a <main> for exactly this reason.
• Color contrast is not covered by the automated suite. The a11y test suite disables axe's color-contrast rule, because headless-Chromium font metrics make that rule unreliable in that environment, not because contrast does not matter.
• Announcement timing is not covered. The tests assert the announcement text and the aria-live structure, not what a screen reader speaks aloud or when.