Headless data grid (table) keyboard navigation library
table-nav is a headless utility library, that enables accessible keyboard navigation of data grids (aka tables).
The ARIA specs for data grid navigation can be found here:
table-nav consists of:
core
: Contains all the logic of the library, which is framework-agnosticreact
: Useful wrappers to work with React projectssvelte
(soon): Useful wrappers to work with Svelte projects. Example link
yarn add @table-nav/core @table-nav/react
To use this library you can either use directly the core
package or the react
package.
Below is an example on how you can use the core
package in a simple HTML table.
This package is framework-agnostic, and you can find an example integration with Svelte here.
// DataGridNav is the main class of the library
import { DataGridNav } from "@table-nav/core";
// Create a new instance of the class
const dataGridNav = new DataGridNav({
// Library is written in TS and all the options will be recommended inside your IDE
debug: true,
});
// Use the function provided by the library to handle the keydown/up events
table.addEventListener("keydown", dataGridNav.tableKeyDown);
table.addEventListener("keyup", dataGridNav.tableKeyUp); // This is neccessery to allow more than 1 key shortcuts
For projects using react, @table-nav/react
provides a useful hook to work with.
// Import hook from "@table-nav/react"
import { useTableNav } from '@table-nav/react';
// Inside your HOC component
const { tableNav, listeners } = useTableNav();
<YourTable {...listeners} />
useTableNav
returns an object with 2 properties:
tableNav
: An instance of the DataGridNav
class. Useful for programmatic navigation, and enabling/disabling the functionality for use-cases, like widget focus inside cell.listeners
: An object with the onKeyDown
and onKeyUp
listeners, that you can spread inside your table element.All the examples inside packages/storybook
are with @table-nav/react
, so feel free to take a look how they work.
Key | Description |
---|---|
Moves focus one cell to the right. If focus is on the right-most cell in the row, focus does not move. | |
Moves focus one cell to the left. If focus is on the left-most cell in the row, focus does not move. | |
Moves focus one cell up. If focus is on the top cell in the column, focus does not move. | |
Moves focus one cell down. If focus is on the bottom cell in the column, focus does not move. | |
Moves focus down an author-determined number of rows, typically scrolling so the bottom row in the currently visible set of rows becomes one of the first visible rows. If focus is in the last row of the grid, focus does not move. | |
Moves focus up an author-determined number of rows, typically scrolling so the top row in the currently visible set of rows becomes one of the last visible rows. If focus is in the first row of the grid, focus does not move. | |
Moves focus to the first cell in the row that contains focus. | |
Moves focus to the last cell in the row that contains focus. | |
Moves focus to the first cell in the first row. | |
Moves focus to the first cell in the last row. | |
Disables grid navigation and focuses on the first focusable element in the cell. If there are no focusable elements in the cell. |
Note WTF (What the focus) is going on. There is no standardised way to know what is actually focusable in the web. To comply with this lib and work properly, you need to add a
tabindex
attribute explicitly to the elements you want to be focusable, inside a cell, except forinput
andtextarea
elements.
Key | Description |
---|---|
Restores grid navigation. | |
If the cell contains multiple widgets, moves focus to the next widget inside the cell, optionally wrapping to the first widget if focus is on the last widget. Otherwise, passes the key event to the focused widget.Arrow Down is disabled issue
|
|
If the cell contains multiple widgets, moves focus to the previous widget inside the cell, optionally wrapping to the first widget if focus is on the last widget. Otherwise, passes the key event to the focused widget. Arrow Up is disabled issue
|
The below keystrokes are supported natively by browsers, so they are not implement
Tab
: moves focus to the next widget in the grid. Optionally, the focus movement may wrap inside a single cell or within the grid itself. (As described, there should be no trap focus inside a grid cell).Shift + Tab
: moves focus to the previous widget in the grid. Optionally, the focus movement may wrap inside a single cell or within the grid itself.If you want a feature that is not supported or found a bug that you want to fix, fork the repo, and then make a PR with your proposed changes. Still a small project so there are no strict guidelines.