gridcn2.0.0
Accessibility

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-label or aria-labelledby on 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 announceResults to 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

GapEffectWorkaround
The fill handle is pointer-onlyIt 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 navigationA 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 keysThe 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 landmarkRegion 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-descriptionThe 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 testThe axe-core suite turns off the color-contrast rule.Check your theme colors with a contrast tool.
No screen reader testThe repository records no manual pass with a screen reader.Test your grid with the screen readers that your users run.
Announcement timing has no testTests 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.

On this page