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:
| Position | Rows |
|---|---|
| First | Header rows: one per group level, then the column header row. |
| Second | Pinned-top rows. |
| Third | Data rows. |
| Last | Pinned-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"whileloadingis 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 exposesaria-labelandaria-valuetextfromlabels.grid.loading. A screen reader does not read it aloud. - A custom
loadingStatereplaces 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.
Related
- Keyboard test coverage: what the tests check
- Accessibility gaps: what they leave out
- Live region messages: what the live region reads
- Screen reader announcements example: the live region on screen
Row limits
Look up how many rows one grid scrolls, from the 100,000-row test size to the browser height limits in Firefox and Chromium.
Live region messages
Look up what the grid live region reads and the label that sets each message, from row moves and checks to stale views, refused saves, and load results.