Accessibility gaps
Look up what the grid does not cover for assistive technology, the effect of each gap, and the workaround.
This page lists known gaps in accessibility and in the tests. Use the workaround column. Do not read the absence of a gap here as a conformance claim.
What your page adds
The grid brings its roles, focus, and live regions. Your page adds these parts:
- Set
aria-labeloraria-labelledbyon the grid, so the grid has a name. In development, the grid warns once when it has neither prop. A labelled ancestor does not name the grid. - Wrap the grid in a labeled
<section>or another landmark. See Place the grid in a landmark. - Place that section inside
<main>or another landmark. - Check the colors of your theme with a contrast tool. See Color contrast.
- Set
announceResultsto read the row count after a filter or a sort change. - Test the page with a screen reader. The repository records no manual pass.
Known gaps
| Gap | Effect | Workaround |
|---|---|---|
| The fill handle is pointer-only | It has no keyboard equivalent and is hidden from assistive technology. | Press Mod+D to fill down or Mod+R to fill right. Mod is Cmd on Apple platforms and Ctrl elsewhere. |
| Pinned rows are outside navigation | A pinned row is never the active cell. It has no tabindex and no aria-selected. | Do not put a task that needs the keyboard in a pinned row. |
| Column reorder and resize have no default keys | The default keymap does not move or resize a column. | Bind moveColumnTowardStart, moveColumnTowardEnd, widenColumn, and narrowColumn in keymap to move and resize columns from the keyboard. The header menu holds the same commands. |
| The grid has no page landmark | Region navigation cannot place the grid in a labeled region, and the axe-core region rule reports it. | Place the grid inside <main> or a labeled <section>. |
A cell error text depends on aria-description | The cell carries its error message in aria-description. Screen readers differ in how they read this attribute. | Show the error text in your own page as well, for example in a list next to the grid. |
| Color contrast has no test | The axe-core suite turns off the color-contrast rule. | Check your theme colors with a contrast tool. |
| No screen reader test | The repository records no manual pass with a screen reader. | Test your grid with the screen readers that your users run. |
| Announcement timing has no test | Tests assert the announcement text and the aria-live structure. They do not assert what a screen reader says or when. | Listen to your flows with a screen reader. |
Place the grid in a landmark
A registry component cannot own the page shell, so the page supplies the landmark. One axe-core fixture of the test suite wraps the grid in a <main> for this reason. The other turns the region rule off. The next sample names a region, names the grid, and puts the grid inside the region:
import { DataGrid, defineColumns } from "@/components/data-grid/data-grid";
type Task = { id: string; title: string };
const columns = defineColumns<Task>()([
{ id: "title", header: "Title", accessorKey: "title" },
] as const);
const getRowId = (task: Task) => task.id;
export function Tasks({ tasks }: { tasks: Task[] }) {
return (
<section aria-label="Tasks">
<DataGrid
aria-label="Tasks"
data={tasks}
columns={columns}
getRowId={getRowId}
/>
</section>
);
}Color contrast
Headless Chromium font metrics make the color-contrast rule unreliable, so the suite turns it off. The rule matters. Your theme sets the colors, so check them in your own pages.
Related
- Screen reader support: what the grid exposes
- Keyboard test coverage: what the tests check
- Pinned rows: pinned rows and navigation
- Fill handle: fill from the keyboard