UnflowUI
ComponentsHooks

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.

ParamTypeDefaultDescription
orientation'vertical' | 'horizontal''vertical'Which arrow pair moves focus
itemSelectorstring'[data-focus-item]'Selector for the items inside the container

Return value

TypeDescription
(event: KeyboardEvent<HTMLElement>) => voidPass 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

KeyBehavior
ArrowUp (vertical) / ArrowLeft (horizontal)Previous item, wrapping to the last
ArrowDown (vertical) / ArrowRight (horizontal)Next item, wrapping to the first
HomeFirst item
EndLast item
TabBrowser 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.