React Data GridAccessibility

Handsontable is designed to be accessible, aligning with global standards. We prioritize inclusivity, ensuring web applications are usable by people with disabilities.

Overview

Accessibility features of Handsontable include:

  • Keyboard navigation that lets you use the grid without a mouse.
  • Support for the most popular screen readers.
  • Flexible API to configure keyboard shortcuts and navigation methods.

Conformance with standards

Most global standards and regulations are created in accordance with WCAG (Web Content Accessibility Guidelines). Handsontable meets requirements outlined in the WCAG 2.1 AA (opens new window) guidelines, which makes it compatible with most local standards, such as:

Region

USA

Europe

Canada

Keyboard navigation

Handsontable doesn't require a mouse to navigate across the grid's elements. This is an important feature for those users with temporary or permanent motor impairments for whom following the mouse cursor is difficult. Keyboard navigation is also a great way to improve productivity, which is why many users choose the keyboard over the mouse regardless of their accessibility needs.

Our experience with hundreds of implementations shows that Handsontable tends to be used either as a spreadsheet application or a data grid component. While at first the difference seems subtle, it significantly impacts user expectations regarding navigation.

In a typical spreadsheet application (think of Microsoft Excel or Google Sheets), you can't move the focus onto headers. This makes it difficult to sort or filter data without knowing complex keyboard shortcuts. Additionally, opening a column menu is not trivial. Handsontable offers flexibility in this regard, allowing users to switch between data grid and spreadsheet "modes". To do that switch, you can use a combination of two options: navigableHeaders to enable or disable moving focus onto headers, and tabNavigation to decide if the Tab key can be used to navigate across cells and headers.

The following table provides more details about these two scenarios:

Aspect Data grid mode Spreadsheet mode (default)
Configuration navigableHeaders: true
tabNavigation: false
navigableHeaders: false
tabNavigation: true
Primary navigation method Arrow keys Tab / Shift+Tab
Navigable headers Yes No
Navigation Use the arrow keys navigate across the grid. Use simple shortcuts such as Enter or Space to open menus or interact with headers, cells, or cell editors.

You can't use the Tab key for navigation.
Use Tab / Shift+Tab to navigate across the grid.
This behavior is similar to Excel or Google Sheets.

To open menus, use more complex shortcuts.
Focus behavior One tab stop. The grid is included in the page tab sequence only once. Multiple tab stops. All tabbable elements of the grid, such as cells, are included in the page tab sequence.

Handsontable provides a wide range of keyboard shortcuts, but some of them are particularly important for users who navigate the grid with the keyboard only. For example, actions triggered while navigating across headers involve simple key combinations, making them intuitive and useful. For more complex scenarios, you can customize the shortcuts keys through the API.

Windows macOS Action Focused element
Shift+Alt+ Shift+Option+ Open a column menu Any cell
Ctrl+Enter Cmd+Enter Open a column menu Column header
Enter Enter Sort data Column header
Alt+A Option+A Clear filters Any cell
Ctrl+Space Ctrl+Space* Select a column Any cell
Shift+Space Shift+Space Select a row Any cell
Ctrl+Shift+\
Shift+F10
Cmd+Shift+\
Shift+F10
Open a context menu Any cell

*To use this shortcut, disable the default macOS behavior for the Ctrl+Space key combination, under System Settings > Keyboard > Keyboard Shortcuts > Input Sources.

Support for screen readers

Although semantic HTML doesn't need any additional attributes to be properly interpreted by assistive technologies, some of Handsontable's complex features are not fully covered by the HTML specification. That's why Handsontable provides support for screen readers with ARIA attributes (Accessible Rich Internet Applications) applied to its HTML markup.

Each new version of Handsontable is thoroughly tested for accessibility with the following screen readers:

  • NVDA (Windows)
  • JAWS (Windows)
  • VoiceOver (macOS)

Accessible data grid demo

Check out the interactive demo below to see how various Handsontable settings impact its accessibility level and affect the user experience.

    Disabling DOM virtualization for improved accessibility

    By default, Handsontable uses DOM virtualization to display only the rows and columns that are currently visible on the screen, plus a few extra cells outside the visible area to ensure a seamless scrolling experience.

    However, assistive technologies rely on the elements within the DOM appearing in the correct order. Otherwise, they require the use of additional ARIA attributes (opens new window), such as row-colindex or aria-rowindex, to understand the grid's structure and accurately announce (read) it to the user.

    We already use ARIA attributes to describe data sorting, hidden columns or rows, and merged cells. Unfortunately, our tests have discovered scenarios where screen readers either announce incorrect indices or omit the ARIA attributes altogether. To address this issue, we recommend disabling DOM virtualization, which entails loading all grid elements into the browser. This action creates a complete Accessibility tree (opens new window) that can be easily parsed and interpreted by assistive technology.

    <HotTable
      // disable column virtualization
      renderAllColumns={true}
      // disable row virtualization
      renderAllRows={true}
    />
    

    High-contrast theme

    The recommended minimum contrast ratio (opens new window) for text against images or backgrounds is 4.5:1. To achieve this level of contrast with Handsontable's default theme, you can:

    Requirements for developers

    When you customize Handsontable, it's you who's responsible for ensuring the accessibility of your solution. Especially when you create a custom cell type or a custom plugin, remember to make them accessible to everyone.

    Our recommendations for custom development:

    • Test your code against WCAG 2.1 requirements frequently.
    • Use proper color contrast, font size, and semantic HTML.
    • If needed, implement additional WAI-ARIA attributes.
    • Avoid flashing or blinking content.
    • Test your customizations with real users who have different types of disabilities. If you don’t have access to real users, try Funkify (opens new window), a disability simulator, which can help you look at your application from the perspective of users with different disabilities.

    TIP

    The quality of custom Handsontable modifications can impact your application's accessibility level. Make sure to actively check how your changes influence the overall accessibility of your application, using tools like Lighthouse (opens new window).

    Maintaining accessibility

    We make sure our data grid remains accessible by taking the following measures:

    • We check Handsontable's accessibility score with a range of accessibility testing tools.
    • We use automated visual regression testing.
    • We manually test all of Handsontable's features with the most popular screen readers.
    • We use automated unit and end-to-end tests.

    Known limitations

    • When frozen rows, frozen columns, or both, are enabled, some screen readers may incorrectly read the total number of rows and columns.
    • When you select a cell that's part of a frozen row, frozen column, or both, NVDA and JAWS might incorrectly announce that cell's column header name.
    • Dynamic ARIA attributes are sometimes omitted by screen readers.
    • The aria-rowcount attribute is intentionally set to -1, as most screen readers either ignore or misinterpret it. This configuration ensures accuracy with screen readers such as VoiceOver. We plan to revise this approach once screen readers consistently handle the aria-rowcount attribute correctly.

    API reference

    For the list of options, methods, and Handsontable hooks related to accessibility, see the following API reference pages:

    Troubleshooting

    Try the following links if you didn't find what you need: