react-roving-focus

Flexible roving focus (aka roving tabindex) for React with support for any fixed or responsive layout.

!MIT License

Examples

Refer to the Storybook for various layout examples:

- Horizontal layout
- Vertical layout
- Grid layout
- Responsive grid layout
- Nested grid layout
- Masonry layout (aka modular grid)

How it works

Unlike traditional roving tabindex implementations, react-roving-focus determines navigation order using the rendered size and position of elements, rather than row or column indices. This enables keyboard navigation across any 1D or 2D layout (fixed or responsive) without any configuration.

$3

Use the following keys to move focus between elements:

| Key | Function |
| :---------------------------- | :--------------------------------------------------------- |
| Tab | Move to next or focusable element |
| Shift + Tab | Move to previous or focusable element |
| ← (left arrow) | Move focus to element on the left |
| → (right arrow) | Move focus to element on the right |
| ↑ (up arrow) | Move focus to element above |
| ↓ (down arrow) | Move focus to element below |
| Home (or fn + ← on Mac) | Move focus to first element in the |
| End (or fn + → on Mac) | Move focus to last element in the |

$3

To minimize re-renders, each element maintains its own tabIndex state via the useRovingFocus() hook. The updates individual tabIndex state values in response to element registration, unregistration, focus changes, and enabled/disabled state changes.

The determines the 'first' and 'last' elements during registration and unregistration. To track accessibility state changes, a MutationObserver monitors the disabled and aria-disabled attributes of all registered elements.

When an arrow key is pressed, the 'next' element is calculated using multi-level filtering and simple distance calculations for efficiency. Element positions are intentionally not cached since layout changes (particularly those driven by state) may not be automatically detectable.

Performance has been stress tested using various layouts with 10,000 focusable elements.

Installation

``bash
npm install react-roving-focus


or

pnpm add react-roving-focus

or

bun add react-roving-focus
`

Usage

Wrap a group of focusable elements in a and use the useRovingFocus() hook to control the tabIndex of each element.

`tsx
import { RovingFocusGroup, useRovingFocus } from 'react-roving-focus';

function ExampleGroup() {
return (



);
}

function ExampleItem({ children }: { children: React.ReactNode }) {
const { ref, tabIndex } = useRovingFocus();

return (

{children}

);
}
`

$3

If a focusable element has an existing ref, provide it to the useRovingFocus() hook.

`tsx
import { useRef } from 'react';
import { useRovingFocus } from 'react-roving-focus';

function ExampleItem({ children }: { children: React.ReactNode }) {
const buttonRef = useRef(null);
const { tabIndex } = useRovingFocus({ ref: buttonRef });

return (

{children}

);
}
`

$3

To disable a focusable element, set the disabled or aria-disabled attribute on the focusable element.

`tsx
import { useRovingFocus } from 'react-roving-focus';

function ExampleItem({ children }: { children: React.ReactNode }) {
const { ref, tabIndex } = useRovingFocus();

return (

{children}

);
}
`

Alternatively, set disabled: true in the useRovingFocus() hook.

`tsx
import { useRovingFocus } from 'react-roving-focus';

function ExampleItem({ children }: { children: React.ReactNode }) {
const { ref, tabIndex } = useRovingFocus({
disabled: true,
});

return (

{children}

);
}
``