useArrowNavigation
Fires previous/next callbacks on a pair of arrow keys anywhere on the page, without hijacking typing in fields. Used by ItemNav, Pagination, Toolbar and DataTable.
Overview
useArrowNavigation listens on document for one pair of arrow keys and calls onPrevious or onNext. Use it for page-level "previous/next" actions, such as stepping through records or pages, where the arrow keys should work without first focusing a control.
It is used by ItemNav, Pagination, Toolbar and DataTable.
Import
import { useArrowNavigation } from '@unflowio/ui/hooks/useArrowNavigation';Parameters
| Param | Type | Default | Description |
|---|---|---|---|
listen | boolean | true | Whether the listener is on. Set it to false while another control owns the arrow keys |
onPrevious | () => void | undefined | Called on ArrowUp (vertical) or ArrowLeft (horizontal) |
onNext | () => void | undefined | Called on ArrowDown (vertical) or ArrowRight (horizontal) |
orientation | 'vertical' | 'horizontal' | 'vertical' | Which arrow pair to listen for |
Return value
None.
Usage
import { useCallback, useState } from 'react';
import { useArrowNavigation } from '@unflowio/ui/hooks/useArrowNavigation';
function RecordViewer({ records }: { records: { id: string; title: string }[] }) {
const [index, setIndex] = useState(0);
const previous = useCallback(() => setIndex((i) => Math.max(0, i - 1)), []);
const next = useCallback(
() => setIndex((i) => Math.min(records.length - 1, i + 1)),
[records.length],
);
useArrowNavigation({ onPrevious: previous, onNext: next });
return <h2>{records[index]?.title}</h2>;
}Wrap the callbacks in useCallback: they are effect dependencies, so new functions on every render re-register the listener.
Adding a letter shortcut
Arrow keys are not part of useHotkey's combos. To also support keys like j/k, register them with useHotkey and point them at the same callbacks:
useArrowNavigation({ onPrevious: previous, onNext: next });
useHotkey({ keys: ['k'], action: previous });
useHotkey({ keys: ['j'], action: next });Keyboard behavior
| Key | vertical | horizontal |
|---|---|---|
ArrowUp | onPrevious | — |
ArrowDown | onNext | — |
ArrowLeft | — | onPrevious |
ArrowRight | — | onNext |
A handled key is preventDefault'd, so the page does not scroll.
Implementation notes
Typing is never hijacked. Keys pressed in an input, textarea, select or contenteditable element are ignored.
Already-handled keys are skipped. If another handler called preventDefault() first (for example a Select trigger opening its menu on ArrowDown), the hook does nothing, so the key never does two things.
Accessibility
The listener is global, so tell users the keys exist, for example with a Shortcut legend next to the previous/next buttons. Keep visible buttons for the same actions: arrow keys alone are not discoverable and don't work with every assistive technology.
useDragReorder
Native drag-and-drop reordering for a keyed list, with the dragged row and drop edge exposed for styling. Used by ListEditor and ColumnsPanel.
useFocusNavigation
Arrow keys, Home and End move focus between items in a container while every item keeps its own tab stop. Used by NavSection and BottomBar.