gridcn2.0.0
Accessibility

Screen reader support

See the roles, counts, focus rules, loading state, and live regions that the grid gives screen readers.

The grid follows the WAI-ARIA grid pattern.

Conformance target

The target is WCAG 2.2 AA. gridcn makes no conformance claim and has had no conformance audit. The automated checks run axe-core in Chromium on two core fixtures and the saved-views menu. One fixture has a toolbar, markers, a pinned row, and a sort. One has column groups. No manual screen reader pass is on record.

Roles and indices

Roles

The scroll root has role="grid", a rendered row role="row", a data cell role="gridcell", and a column header role="columnheader".

The marker column holds gridcell cells and a columnheader with a screen-reader-only label (labels.markers.columnHeader). A checkbox cell is a display-only role="checkbox" with aria-checked. Its aria-label is the headerText, a string header, or the column id.

Counts and indices

aria-rowcount and aria-colcount sit on the grid root. aria-rowindex sits on rows (1-based). aria-colindex sits on cells and column headers.

aria-rowcount includes the header rows, both pinned-row bands, and every row of the view, rendered or not. A paged grid counts only the shown page. The rows follow this order:

PositionRows
FirstHeader rows: one per group level, then the column header row.
SecondPinned-top rows.
ThirdData rows.
LastPinned-bottom rows.

With column groups, each header row has aria-rowindex. A grid without groups has one header row and no aria-rowindex on it. A group header has aria-colindex for its first column and aria-colspan for the columns it covers. A column that spans several header rows has aria-rowspan.

The marker column sits outside this index space. It has no aria-colindex. aria-colcount counts the visible data columns only. Virtualization mounts a subset of columns, and each mounted cell keeps its true aria-colindex.

Sort and state

A sortable column header has aria-sort set to ascending, descending, or none. The attribute appears in every headerClickBehavior mode. The visual arrow shows on every sorted column that has a string header. A column with sortable: false has aria-sort and an arrow only while a sort that your code set applies to it. The header click never sorts it.

With readOnly, the root has aria-readonly. While any of enableRangeSelection, enableRowSelection, enableColumnSelection, or enableMultiRange is true, the root has aria-multiselectable. All four default to true.

A cell with a validation error has aria-invalid="true" and the message in aria-description. While the cell is in edit mode, the message also shows in an element with role="alert". In forced colors mode, an error draws a dashed outline, a search match draws a solid outline, and the active cell draws a solid outline.

Focus, selection, and loading

Roving tabindex

The grid uses the roving tabindex pattern. Before a cell is active, the root of a grid with rows is the one tab stop (tabindex="0"). Once a cell is active, only that cell has tabindex="0". The other cells and the root have -1. With zero rows, the root has -1.

With zero rows, the filter button of each column is a tab stop, or the menu button when the column has no filter button. A header with neither has no tab stop. While the view has rows, no header is a tab stop.

DOM focus follows the active cell. The active row stays mounted after it scrolls out of view, so focus stays. Pinned-row cells and skeleton cells have no tabindex.

Selection

The active cell and every cell of a range, a checked row, or a selected column has aria-selected="true".

A checked row has aria-selected="true" on the row. A cell range does not set it. With a checkbox marker (rowMarkers is "checkbox", "both", "reorder-checkbox", or "reorder-both"), an unchecked row has aria-selected="false". Without one, an unchecked row has no aria-selected.

Editors

A text editor is a native <input> inside the gridcell, so a screen reader reads it as a form field. Select and date editors open a popup. When the editor closes, focus returns to the cell. If a commit moved focus to a control outside the grid with Tab, focus stays on that control.

Loading state

  • The root has aria-busy="true" while loading is true.
  • The skeleton (zero rows) and the slim bar (rows present) are hidden from the accessibility tree.
  • While the grid draws its own loading state, a visually hidden role="progressbar" outside the grid exposes aria-label and aria-valuetext from labels.grid.loading. A screen reader does not read it aloud.
  • A custom loadingState replaces the skeleton or the bar. The grid adds no role, label, or progressbar. The node owns its accessibility.
  • In scroll mode, a row and its cells that have not arrived have aria-busy="true".
  • A row with a save in flight has aria-busy="true".

Live regions

Each grid adds one role="status" live region with aria-live="polite". Live region messages lists what it reads and the label that sets each message.

On this page