ARIA-friendly grid

In this tutorial, you will configure Handsontable DataGrid for screen reader compatibility. You will learn how to use ariaTags, tabMoves, aria-label on cells, and aria-sort on headers for a grid that targets WCAG 2.2 Level A and AA.

1
import { HotTable } from '@handsontable/react-wrapper';
2
import { registerAllModules } from 'handsontable/registry';
3
import { getRenderer } from 'handsontable/renderers';
4

5
registerAllModules();
6

7
/* start:skip-in-preview */
8
const data = [
9
  { name: 'Ana García',    department: 'Engineering',  role: 'Senior Engineer',    salary: 95000,  startDate: '2019-03-12' },
10
  { name: 'James Okafor',  department: 'Product',      role: 'Product Manager',    salary: 105000, startDate: '2020-07-01' },
11
  { name: 'Li Wei',        department: 'Design',       role: 'UX Designer',        salary: 88000,  startDate: '2021-01-15' },
12
  { name: 'Priya Sharma',  department: 'Engineering',  role: 'Tech Lead',          salary: 120000, startDate: '2018-09-05' },
13
  { name: 'Carlos Mendez', department: 'HR',           role: 'HR Specialist',      salary: 72000,  startDate: '2022-02-20' },
14
  { name: 'Sarah Chen',    department: 'Finance',      role: 'Financial Analyst',  salary: 91000,  startDate: '2020-11-30' },
15
  { name: 'Omar Hassan',   department: 'Engineering',  role: 'Backend Engineer',   salary: 98000,  startDate: '2021-06-14' },
16
  { name: 'Emma Wilson',   department: 'Marketing',    role: 'Marketing Lead',     salary: 85000,  startDate: '2019-08-22' },
17
];
18
/* end:skip-in-preview */
19

20
const colHeaders = ['Name', 'Department', 'Role', 'Salary', 'Start Date'];
21

22
const ExampleComponent = () => {
23
  return (
24
    <HotTable
25
      data={data}
26
      colHeaders={colHeaders}
27
      rowHeaders={true}
28
      height="auto"
29
      width="100%"
30
      ariaTags={true}
31
      tabMoves={{ row: 1, col: 0 }}
32
      enterMoves={{ row: 1, col: 0 }}
33
      autoWrapRow={false}
34
      autoWrapCol={false}
35
      columnSorting={true}
36
      columns={[
37
        { data: 'name' },
38
        { data: 'department' },
39
        { data: 'role' },
40
        { data: 'salary' },
41
        { data: 'startDate' },
42
      ]}
43
      cells={function() {
44
        return {
45
          renderer(hotInstance, TD, row, col, prop, value, cellProperties) {
46
            getRenderer('text')(hotInstance, TD, row, col, prop, value, cellProperties);
47
            TD.setAttribute('aria-label', `${colHeaders[col]}: ${value ?? 'empty'}`);
48
          },
49
        };
50
      }}
51
      afterGetColHeader={function(col, TH) {
52
        if (!TH.hasAttribute('aria-sort')) {
53
          TH.setAttribute('aria-sort', 'none');
54
        }
55
      }}
56
      licenseKey="non-commercial-and-evaluation"
57
    />
58
  );
59
};
60

61
export default ExampleComponent;

1
import { HotTable } from '@handsontable/react-wrapper';
2
import { registerAllModules } from 'handsontable/registry';
3
import { getRenderer } from 'handsontable/renderers';
4
import type Handsontable from 'handsontable/base';
5

6
registerAllModules();
7

8
/* start:skip-in-preview */
9
type EmployeeRow = {
10
  name: string;
11
  department: string;
12
  role: string;
13
  salary: number;
14
  startDate: string;
15
};
16

17
const data: EmployeeRow[] = [
18
  { name: 'Ana García',    department: 'Engineering',  role: 'Senior Engineer',    salary: 95000,  startDate: '2019-03-12' },
19
  { name: 'James Okafor',  department: 'Product',      role: 'Product Manager',    salary: 105000, startDate: '2020-07-01' },
20
  { name: 'Li Wei',        department: 'Design',       role: 'UX Designer',        salary: 88000,  startDate: '2021-01-15' },
21
  { name: 'Priya Sharma',  department: 'Engineering',  role: 'Tech Lead',          salary: 120000, startDate: '2018-09-05' },
22
  { name: 'Carlos Mendez', department: 'HR',           role: 'HR Specialist',      salary: 72000,  startDate: '2022-02-20' },
23
  { name: 'Sarah Chen',    department: 'Finance',      role: 'Financial Analyst',  salary: 91000,  startDate: '2020-11-30' },
24
  { name: 'Omar Hassan',   department: 'Engineering',  role: 'Backend Engineer',   salary: 98000,  startDate: '2021-06-14' },
25
  { name: 'Emma Wilson',   department: 'Marketing',    role: 'Marketing Lead',     salary: 85000,  startDate: '2019-08-22' },
26
];
27
/* end:skip-in-preview */
28

29
const colHeaders: string[] = ['Name', 'Department', 'Role', 'Salary', 'Start Date'];
30

31
const ExampleComponent = () => {
32
  return (
33
    <HotTable
34
      data={data}
35
      colHeaders={colHeaders}
36
      rowHeaders={true}
37
      height="auto"
38
      width="100%"
39
      ariaTags={true}
40
      tabMoves={{ row: 1, col: 0 }}
41
      enterMoves={{ row: 1, col: 0 }}
42
      autoWrapRow={false}
43
      autoWrapCol={false}
44
      columnSorting={true}
45
      columns={[
46
        { data: 'name' },
47
        { data: 'department' },
48
        { data: 'role' },
49
        { data: 'salary' },
50
        { data: 'startDate' },
51
      ]}
52
      cells={function(): Handsontable.CellMeta {
53
        return {
54
          renderer(
55
            hotInstance: Handsontable,
56
            TD: HTMLTableCellElement,
57
            row: number,
58
            col: number,
59
            prop: string | number,
60
            value: Handsontable.CellValue,
61
            cellProperties: Handsontable.CellProperties,
62
          ): void {
63
            getRenderer('text')(hotInstance, TD, row, col, prop, value, cellProperties);
64
            TD.setAttribute('aria-label', `${colHeaders[col]}: ${value ?? 'empty'}`);
65
          },
66
        };
67
      }}
68
      afterGetColHeader={function(col: number, TH: HTMLTableCellElement): void {
69
        if (!TH.hasAttribute('aria-sort')) {
70
          TH.setAttribute('aria-sort', 'none');
71
        }
72
      }}
73
      licenseKey="non-commercial-and-evaluation"
74
    />
75
  );
76
};
77

78
export default ExampleComponent;

Overview

This recipe shows how to configure Handsontable so screen readers can navigate the grid meaningfully. You will enable ARIA roles on grid elements, add descriptive aria-label attributes to every cell, expose sort state on column headers, and configure keyboard navigation to match screen reader conventions.

Difficulty: Beginner - Intermediate Time: ~15 minutes

What You’ll Build

A grid that:

Exposes role="treegrid", role="row", and role="gridcell" on the DOM elements screen readers expect
Sets aria-label on each cell combining the column name and the cell value (e.g., "Name: Ana García")
Marks each column header with aria-sort="none" initially, updated to ascending or descending when sorted
Moves focus one row down on both Tab and Enter so keyboard users advance predictably
Keeps wrap-around navigation off, so focus never jumps to the opposite end of the grid

Before you begin

No additional dependencies are required. This recipe uses only the Handsontable core library.

If you have not set up a Handsontable project yet, follow the Quick start guide first.

Keep ARIA roles on with ariaTags
```
1
const hot = new Handsontable(container, {
2
  ariaTags: true,
3
  // ...
4
});
```
What’s happening: ariaTags is true by default, so Handsontable already stamps role="treegrid" on the grid’s root element, role="row" on each row element, and role="gridcell" on each data cell. The example sets it explicitly so the dependency is visible. These roles come from ARIA’s grid pattern and let screen readers announce the structure of the table.

With ariaTags: false the DOM is still a visual table, but screen readers have no semantic cues to describe rows and cells as belonging to an interactive data grid. Set it to false only when you add your own ARIA markup.
Configure Tab and Enter navigation for screen readers
```
1
const hot = new Handsontable(container, {
2
  tabMoves:   { row: 1, col: 0 },
3
  enterMoves: { row: 1, col: 0 },
4
  // ...
5
});
```
What’s happening:
- tabMoves: { row: 1, col: 0 } makes Tab move to the next row in the same column instead of the next column. Screen reader users typically use Tab to move between interactive regions, and moving row-by-row matches that mental model better than moving cell-by-cell.
- enterMoves: { row: 1, col: 0 } makes Enter commit a cell edit and advance one row down. This mirrors spreadsheet conventions that screen reader users already know.
Both options accept a { row, col } object. Negative values move backwards.
Keep wrap-around navigation off
```
1
const hot = new Handsontable(container, {
2
  autoWrapRow: false,
3
  autoWrapCol: false,
4
  // ...
5
});
```
What’s happening: autoWrapRow and autoWrapCol are false by default, so the selection stops at the grid’s edges. When either is true, pressing Tab on the last column wraps focus to the first column of the next row, and pressing Tab on the last cell of the grid wraps back to the first cell. For sighted users this is convenient. For screen reader users it is disorienting — the reader may announce a sudden column or row change that appears to have no cause.

Keeping both autoWrapRow and autoWrapCol at false makes the grid stop at the boundaries, which matches what screen reader users expect from a navigation region. The example sets them explicitly so a grid-level configuration that turns wrapping on cannot change this.
Add aria-label to cells with a custom renderer
```
1
const colHeaders = ['Name', 'Department', 'Role', 'Salary', 'Start Date'];
2

3
const hot = new Handsontable(container, {
4
  colHeaders,
5
  cells() {
6
    return {
7
      renderer(hotInstance, TD, row, col, prop, value, cellProperties) {
8
        getRenderer('text')(hotInstance, TD, row, col, prop, value, cellProperties);
9
        TD.setAttribute('aria-label', `${colHeaders[col]}: ${value || 'empty'}`);
10
      },
11
    };
12
  },
13
  // ...
14
});
```
What’s happening: The cells() callback returns a renderer for every cell. Inside the renderer:
1. getRenderer('text')(...) runs the built-in text renderer first. This ensures default rendering behavior (escaping, class names) is preserved.
2. TD.setAttribute('aria-label', ...) adds a human-readable label. The format "Column: value" gives screen readers a concise, self-contained description of each cell, for example "Salary: 95000" instead of just "95000".
Passing value || 'empty' ensures that blank cells are announced as "Name: empty" rather than "Name: ", which some screen readers skip entirely.

Why use cells() instead of columns? cells() applies the renderer to every column in one place. If you need column-specific formatting alongside the aria-label, move the renderer into each entry in the columns array instead.
Set aria-sort on column headers
```
1
const hot = new Handsontable(container, {
2
  columnSorting: true,
3

4
  afterGetColHeader(col, TH) {
5
    if (!TH.hasAttribute('aria-sort')) {
6
      TH.setAttribute('aria-sort', 'none');
7
    }
8
  },
9
  // ...
10
});
```
What’s happening: The afterGetColHeader hook fires every time Handsontable renders a column header. The callback receives the visual column index (col) and the <th> DOM element (TH).

The aria-sort attribute on a column header tells screen readers whether the column is sorted and in which direction. WCAG 2.2 Success Criterion 1.3.1 requires that sort state is conveyed programmatically, not just visually.

The check !TH.hasAttribute('aria-sort') avoids overwriting aria-sort when the ColumnSorting plugin has already set it. With columnSorting enabled and ariaTags on, the plugin sets aria-sort on every column header it renders: "none" before sorting, "ascending" or "descending" after. The hook is a safety net for a header the plugin does not own, for example one you render yourself. Screen readers do not announce a change of the sort order yet; see the known limitations in the Accessibility guide.

How It Works - Complete Flow

Initial render — ariaTags: true stamps role="treegrid", role="row", and role="gridcell" on the DOM. The ColumnSorting plugin sets aria-sort="none" on each header, and the afterGetColHeader hook adds it to any header that has none. The custom renderer sets aria-label="Column: value" on each cell.
User presses Tab — Focus moves to the next row in the same column (not the next cell sideways). Screen readers announce the new row.
User presses Enter — Any open editor commits the value and focus moves one row down.
User clicks a column header — The columnSorting plugin sorts the data and updates aria-sort on the header to "ascending" or "descending". The custom renderer re-runs and updates all aria-label attributes to reflect the new row order.
User reaches the grid boundary — Tab and Enter stop. No unexpected wrap-around jump occurs.

Testing with Chrome DevTools Accessibility panel

To verify the ARIA attributes are present:

Open the page in Chrome and right-click the grid.
Select Inspect.
In the Elements panel, click the Accessibility tab (top right area of DevTools).
Select any <td> inside the grid. The Accessibility panel shows the computed role (gridcell) and the aria-label value.
Select a <th> in the column header row and verify aria-sort is present.
Click a column header to sort, then re-select the <th>. The aria-sort attribute should update to ascending or descending.

You can also use the Full Page Accessibility Tree (the document icon in the Accessibility panel) to browse all roles and labels without needing to click individual elements.

What you learned

ariaTags: true (the default) adds the semantic roles (treegrid, row, gridcell) that screen readers rely on.
A custom renderer calling TD.setAttribute('aria-label', ...) gives every cell a descriptive, self-contained label.
The ColumnSorting plugin sets aria-sort on each header it renders; the afterGetColHeader hook adds aria-sort="none" to a header that has none.
tabMoves and enterMoves set to { row: 1, col: 0 } align keyboard navigation with screen reader conventions.
autoWrapRow and autoWrapCol stay false (their default), so focus never jumps across a grid boundary.

Next steps

Explore the full ARIA Grid pattern in the WAI-ARIA Authoring Practices.
Add aria-live regions outside the grid to announce data loading states when used with the DataProvider plugin.
Test with a real screen reader. Handsontable is tested with VoiceOver (macOS and iOS) and NVDA (Windows), the matrix of the accessibility conformance report.
Review WCAG 2.2 Success Criterion 4.1.2 for the full Name, Role, Value requirement that aria-label and role attributes address.

ARIA-friendly grid

Overview

What You’ll Build

Before you begin

Keep ARIA roles on with `ariaTags`

Configure Tab and Enter navigation for screen readers

Keep wrap-around navigation off

Add `aria-label` to cells with a custom renderer

Set `aria-sort` on column headers

How It Works - Complete Flow

Testing with Chrome DevTools Accessibility panel

What you learned

Next steps

ARIA-friendly grid

Overview

What You’ll Build

Before you begin

Keep ARIA roles on with ariaTags

Configure Tab and Enter navigation for screen readers

Keep wrap-around navigation off

Add aria-label to cells with a custom renderer

Set aria-sort on column headers

How It Works - Complete Flow

Testing with Chrome DevTools Accessibility panel

What you learned

Next steps

Keep ARIA roles on with `ariaTags`

Add `aria-label` to cells with a custom renderer

Set `aria-sort` on column headers