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.
Overview
useFocusNavigation returns a keydown handler for a container. Arrow keys move DOM focus to the previous or next item (wrapping at the ends), and Home/End jump to the first and last. Unlike a roving tabindex (useListNavigation), it doesn't change tabIndex, so Tab still visits every item. That suits navigation links, where each link is its own stop.
It is used by NavSection in the Sidebar and by BottomBar.
Import
import { useFocusNavigation } from '@unflowio/ui/hooks/useFocusNavigation';Parameters
All optional; call it with no argument for the defaults.
| Param | Type | Default | Description |
|---|---|---|---|
orientation | 'vertical' | 'horizontal' | 'vertical' | Which arrow pair moves focus |
itemSelector | string | '[data-focus-item]' | Selector for the items inside the container |
Return value
| Type | Description |
|---|---|
(event: KeyboardEvent<HTMLElement>) => void | Pass as the container's onKeyDown |
Usage
import { useFocusNavigation } from '@unflowio/ui/hooks/useFocusNavigation';
function SectionLinks() {
const onKeyDown = useFocusNavigation({ orientation: 'horizontal' });
return (
<nav aria-label="Sections" onKeyDown={onKeyDown}>
<a data-focus-item href="#overview">Overview</a>
<a data-focus-item href="#usage">Usage</a>
<a data-focus-item href="#api">API</a>
</nav>
);
}With a custom selector:
const onKeyDown = useFocusNavigation({ itemSelector: 'button' });Keyboard behavior
| Key | Behavior |
|---|---|
ArrowUp (vertical) / ArrowLeft (horizontal) | Previous item, wrapping to the last |
ArrowDown (vertical) / ArrowRight (horizontal) | Next item, wrapping to the first |
Home | First item |
End | Last item |
Tab | Browser default: the next item, then out of the container |
Implementation notes
Disabled items are skipped. Items matching :disabled or [aria-disabled="true"] are left out.
Only acts when focus is on an item. If focus is elsewhere in the container (or the item list is empty), keys pass through untouched.
Items are read from the DOM on each key press, in DOM order, so items added or removed later are picked up automatically. The selected item must be focusable itself (a link, a button, or an element with tabIndex).
Accessibility
Use it for groups where each item is a real link or button and a separate tab stop is expected. For composite widgets that should take a single tab stop (menus, listboxes, toolbars) use a roving tabindex instead.
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.
useListNavigation
Keyboard navigation for a single-column list, with a roving tabindex or, for virtualized lists, aria-activedescendant. Used by List.