keys/hooks/use-navigation

useNavigation

standalonenavigationlist

Standalone keyboard navigation for role-based lists. Uses DOM queries to find navigable items. No provider needed.

useNavigation adds arrow-key navigation, selection, and focus tracking to any list of role-attributed elements. It is standalone — it returns an onKeyDown handler you attach to the container and needs no provider. Items are discovered from the DOM by ARIA role, so the hook stays declarative and works with whatever markup you already render.

tsx

1 const { highlighted, onKeyDown } = useNavigation({2   containerRef,3   role: "option",4 })

When to use it

Listboxes, menus, radio groups, tab bars, and command lists embedded inside a single component.
Cases where you control the container and can attach onKeyDown directly.
Copy-paste consumers that want list navigation without pulling in KeyboardProvider.

When arrow keys should work without the user first clicking into the list, or the list is the main content of a panel that must respect a scope stack, use useScopedNavigation instead. For deeper guidance see the navigation guide.

DOM contract

Three things must hold for item discovery to work:

A container element with a ref passed as containerRef.
Child elements with a matching role attribute.
Each child carries a data-value attribute — the value the hook reports as highlighted and passes to onSelect / onEnter.

Typing `data-value` (`TValue`)

The TValue generic narrows highlighted, onHighlightChange, onSelect, and onEnter to a literal union for editor convenience — but it is a type assertion, not runtime validation. Every value originates from the data-value DOM attribute and is asserted to TValue at the DOM boundary; the hook never checks that the attribute actually belongs to your union. Instantiating with useNavigation<"a" | "b"> makes TypeScript treat the values as "a" | "b", yet a stray data-value="c" is still delivered with full type confidence. Keep your data-value attributes in sync with the union you instantiate, or validate the string inside your callback before relying on it.

Installation

$pnpm exec dgadd add keys/navigation

[Installs to]src/hooks/use-navigation.ts[Item]keys/navigation

dgadd ships in @diffgazer/add on npm: pnpm add -D @diffgazer/add puts it on pnpm exec, and npx @diffgazer/add runs it without the install.

@diffgazer/keys requires no CSS or Tailwind setup.

Parameters

Name	Type	Default	Description
containerRefrequired	RefObject<HTMLElement \| null>	—	Ref to the container element holding navigable items.
rolerequired	"radio" \| "checkbox" \| "option" \| "menuitem" \| "menuitemcheckbox" \| "menuitemradio" \| "button" \| "tab"	—	ARIA role used to query navigable children within the container.
highlighted	string \| null	—	Controlled highlight value. When provided, the hook operates in controlled mode.
onHighlightChange	(value: string \| null) => void	—	Called when the controlled highlight value should change. Receives null when highlight is cleared.
onSelect	(value: string, event: KeyboardEvent) => void	—	Called when Space selects the highlighted item, and as the Enter fallback when onEnter is not provided.
onEnter	(value: string, event: KeyboardEvent) => void	—	Called when Enter is pressed on the highlighted item. When provided, it overrides the onSelect Enter fallback.
wrap	boolean	true	Wrap around when reaching the first or last item.
enabled	boolean	true	Whether the navigation hook is active.
preventDefault	boolean	true	Call preventDefault() on handled keyboard events.
onNavigationBoundaryReached	(direction: "previous" \| "next", event: KeyboardEvent, key: string) => void	—	Called when the user tries to navigate past the first or last item. Receives the orientation-neutral direction, the originating keyboard event, and the key that hit the boundary.
defaultHighlighted	string \| null	null	Initial highlighted value in uncontrolled mode.
upKeys	string[]	—	Custom key names to move highlight up/left.
downKeys	string[]	—	Custom key names to move highlight down/right.
orientation	"vertical" \| "horizontal"	"vertical"	Navigation axis. Vertical uses ArrowUp/ArrowDown, horizontal uses ArrowLeft/ArrowRight.
skipDisabled	boolean	true	Skip items with aria-disabled="true", data-disabled, or native disabled during navigation.
moveFocus	boolean	false	Move DOM focus to the next item instead of only updating highlight state.
scopeToContainer	boolean	true	Ignore items owned by nested collection containers such as nested radiogroups, listboxes, menus, or tablists.
ownerSelector	string \| null	—	Advanced owner selector override for scoping roles that do not have a standard composite owner.
itemSelector	string	—	Narrow the navigable items to those matching this selector, for containers whose role query is broader than their own item set.

Returns

UseNavigationReturnObject with highlight state and an onKeyDown handler to attach to the container.

Name	Type	Default	Description
highlightedrequired	string \| null	—	The value of the currently highlighted item, or null.
isHighlightedrequired	(value: string) => boolean	—	Returns true if the given value is the highlighted item.
highlightrequired	(value: string \| null) => void	—	Imperatively set the highlighted item. Pass null to clear.
onKeyDownrequired	(event: KeyboardEvent) => void	—	Keyboard event handler to attach to the container element.

Keyboard behavior

Key	Behavior
`ArrowDown` / `ArrowUp`	Move highlight (vertical orientation).
`ArrowRight` / `ArrowLeft`	Move highlight (horizontal orientation).
`Home` / `End`	Jump to the first / last item. Not configurable.
`Enter`	Calls `onEnter(value)`, falling back to `onSelect(value)` when `onEnter` is omitted.
`Space`	Calls `onSelect(value)`.

Selection mirrors ARIA semantics: Space toggles, Enter activates. On every move the hook calls scrollIntoView({ block: "nearest" }) so long lists keep the focused item visible. Custom keys can be supplied with upKeys / downKeys (for example vim-style j / k).

Examples

Basic list navigation

Preview

tsx

1 "use client";2 3 import { useNavigation } from "@diffgazer/keys";4 import { useRef } from "react";5 6 const items = ["Apple", "Banana", "Cherry", "Date", "Elderberry"];7 8 function getOptionId(item: string) {9   return `fruit-${item.toLowerCase()}`;10 }11 12 export default function UseNavigationBasic() {13   const containerRef = useRef<HTMLDivElement>(null);14   const { highlighted, isHighlighted, onKeyDown } = useNavigation({15     containerRef,16     role: "option",17     wrap: true,18     onSelect: (value) => alert(`Selected: ${value}`),19   });20 21   return (22     <div>23       <p>ArrowUp/ArrowDown navigate, Enter selects.</p>24       <div25         ref={containerRef}26         onKeyDown={onKeyDown}27         tabIndex={0}28         role="listbox"29         aria-label="Fruits"30         aria-activedescendant={highlighted ? getOptionId(highlighted) : undefined}31         style={{ padding: 4, border: "1px solid currentColor" }}32       >33         {items.map((item) => (34           // biome-ignore lint/a11y/useFocusableInteractive: WAI-ARIA listbox/activedescendant pattern — options stay non-focusable; the listbox container holds focus and aria-activedescendant tracks the active option.35           <div36             key={item}37             id={getOptionId(item)}38             role="option"39             aria-selected={isHighlighted(item)}40             data-value={item}41             style={{ padding: "4px 8px", fontWeight: isHighlighted(item) ? 700 : 400 }}42           >43             {item}44           </div>45         ))}46       </div>47     </div>48   );49 }50

Horizontal tab navigation

Preview

tsx

1 "use client";2 3 import { useNavigation } from "@diffgazer/keys";4 import { useRef, useState } from "react";5 6 const tabs = [7   { id: "general", label: "General", content: "Manage your account settings and preferences." },8   { id: "security", label: "Security", content: "Configure passwords, 2FA, and login sessions." },9   {10     id: "notifications",11     label: "Notifications",12     content: "Choose which alerts and emails you receive.",13   },14   { id: "billing", label: "Billing", content: "View invoices and update payment methods." },15 ];16 17 export default function UseNavigationTabs() {18   const tabListRef = useRef<HTMLDivElement>(null);19   const [activeTab, setActiveTab] = useState(tabs[0]?.id ?? "general");20 21   const { isHighlighted, onKeyDown } = useNavigation({22     containerRef: tabListRef,23     role: "tab",24     orientation: "horizontal",25     wrap: true,26     highlighted: activeTab,27     onHighlightChange: (value) => {28       if (value !== null) setActiveTab(value);29     },30     moveFocus: true,31   });32 33   const activeContent = tabs.find((t) => t.id === activeTab);34 35   return (36     <div>37       <div38         ref={tabListRef}39         role="tablist"40         aria-label="Settings"41         onKeyDown={onKeyDown}42         style={{ display: "flex", borderBottom: "1px solid currentColor" }}43       >44         {tabs.map((tab) => (45           <button46             key={tab.id}47             id={`tab-${tab.id}`}48             type="button"49             role="tab"50             data-value={tab.id}51             aria-selected={isHighlighted(tab.id)}52             aria-controls={`panel-${tab.id}`}53             tabIndex={isHighlighted(tab.id) ? 0 : -1}54             style={{55               padding: "8px 16px",56               cursor: "pointer",57               fontWeight: isHighlighted(tab.id) ? 700 : 400,58               borderBottom: isHighlighted(tab.id)59                 ? "2px solid currentColor"60                 : "2px solid transparent",61             }}62             onClick={() => setActiveTab(tab.id)}63           >64             {tab.label}65           </button>66         ))}67       </div>68       <div69         id={`panel-${activeTab}`}70         role="tabpanel"71         aria-labelledby={`tab-${activeTab}`}72         style={{ padding: 16 }}73       >74         {activeContent?.content}75       </div>76     </div>77   );78 }79

Notes

Standalone

useNavigation does not require KeyboardProvider. It works with a direct onKeyDown handler attached to the container.

DOM-based item discovery

Navigable items are queried from the DOM using the specified role or the data-diffgazer-navigation-item data contract. Items must have a data-value attribute.

Nested collections

scopeToContainer is enabled by default so items inside a nested owner container are excluded from the parent navigation order.

Controlled and uncontrolled

Pass highlighted + onHighlightChange for controlled mode, or use defaultHighlighted for uncontrolled mode.

Edge cases

Disabled items. With skipDisabled (default), items exposing aria-disabled="true", data-disabled, or native disabled are skipped during movement.
Nested collections. scopeToContainer (default) excludes items owned by a nested collection of the same family — an outer radiogroup ignores radios inside an inner radiogroup.
Boundaries. With wrap: false, hitting the first or last item fires onNavigationBoundaryReached(direction, event, key) instead of wrapping — useful for moving focus to an adjacent region.
moveFocus. By default the hook only updates highlight state. Set moveFocus to also move DOM focus to the highlighted element (common for role="tab").

useScopedNavigation — the provider-backed, scope-aware counterpart.
Navigation guide — controlled vs uncontrolled, orientation, and tab patterns.
Utilities — the DOM helpers behind item discovery.

Source

Highlighted source loads after this disclosure opens. Browse the source repository.