UnflowUI
ComponentsHooks

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

ParamTypeDefaultDescription
listenbooleantrueWhether the listener is on. Set it to false while another control owns the arrow keys
onPrevious() => voidundefinedCalled on ArrowUp (vertical) or ArrowLeft (horizontal)
onNext() => voidundefinedCalled 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

Keyverticalhorizontal
ArrowUponPrevious—
ArrowDownonNext—
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.