keys/hooks/use-scoped-navigation

useScopedNavigation

provider-dependentnavigationscope

Scope-aware keyboard navigation registered via KeyboardProvider. Use when navigation should respect the scope stack (e.g., modals, panels).

useScopedNavigation is the provider-backed sibling of useNavigation. It shares the same DOM item-discovery contract and the same options, but registers its keys through KeyboardProvider instead of returning an onKeyDown handler. Because dispatch goes through the provider, navigation participates in the scope stack and can listen at the document level without the list being focused first.

tsx

1 const { highlighted } = useScopedNavigation({2   containerRef,3   role: "menuitem",4 })

When to use it

The list is the primary content of a panel, dialog, drawer, or command palette and arrow keys should work immediately.
Navigation must be suppressed while a deeper scope (a nested overlay) is active.
You want page-level keys via focusWithinOnly rather than wiring onKeyDown onto a focusable container.

For a list embedded inside a self-contained component — a combobox popup, a dropdown — prefer useNavigation; it avoids the provider dependency.

Typing `data-value` (`TValue`)

useScopedNavigation re-exposes the same TValue generic as useNavigation. It 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 without being checked against the union. Keep your data-value attributes in sync with the union you instantiate, or validate the string inside your callback before relying on it.

Installation

Requires KeyboardProvider and the @diffgazer/keys package, which is not public on npm yet.

Diffgazer packages are not yet published to npm. Until the first release, pack @diffgazer/ui and @diffgazer/keys from the repository and install those tarballs.

@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.
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.
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.
scope	string \| null	—	Keyboard scope name to register navigation handlers under. Pass null to skip registration while a conditional scope is disabled.
focusWithinOnly	boolean	false	Only handle navigation keys when focus is within the container element.
allowInInput	boolean	false	Allow navigation keys while a text-editable element has focus.

Returns

UseScopedNavigationReturnObject with highlight state. No onKeyDown — keys are registered via the provider.

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.

Unlike useNavigation, there is no returned onKeyDown — the provider owns key dispatch.

Keyboard behavior

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

Editable-target filtering is handled by the provider via allowInInput. Scope resolution means that if a deeper scope is active, this hook's bindings are suppressed until it is popped.

Examples

Scoped navigation in a menu

Preview

tsx

1 "use client";2 3 import { KeyboardProvider, useScope, useScopedNavigation } from "@diffgazer/keys";4 import { useId, useRef, useState } from "react";5 6 const commands = ["New File", "Open File", "Save", "Save As", "Close"];7 8 function getOptionId(command: string) {9   return `command-${command.toLowerCase().replace(/\s+/g, "-")}`;10 }11 12 function CommandPalette({ onClose }: { onClose: () => void }) {13   const listRef = useRef<HTMLDivElement>(null);14   const headingId = useId();15 16   useScope("command-palette");17 18   const { highlighted, isHighlighted } = useScopedNavigation({19     containerRef: listRef,20     role: "option",21     wrap: true,22     onSelect: (value) => {23       alert(`Executed: ${value}`);24       onClose();25     },26   });27 28   return (29     <div style={{ marginTop: 8, padding: 8, border: "1px solid currentColor" }}>30       <h3 id={headingId}>Command Palette</h3>31       <p>ArrowUp/ArrowDown navigate; Enter executes.</p>32       <div33         ref={listRef}34         role="listbox"35         tabIndex={0}36         aria-labelledby={headingId}37         aria-activedescendant={highlighted ? getOptionId(highlighted) : undefined}38       >39         {commands.map((cmd) => (40           // biome-ignore lint/a11y/useFocusableInteractive: WAI-ARIA listbox pattern — options stay non-focusable; the listbox container holds focus and aria-activedescendant tracks the active option.41           <div42             key={cmd}43             id={getOptionId(cmd)}44             role="option"45             data-value={cmd}46             aria-selected={isHighlighted(cmd)}47             style={{ padding: "4px 8px", fontWeight: isHighlighted(cmd) ? 700 : 400 }}48           >49             {cmd}50           </div>51         ))}52       </div>53     </div>54   );55 }56 57 function App() {58   const [open, setOpen] = useState(false);59 60   return (61     <div>62       <button type="button" onClick={() => setOpen(true)}>63         Open Command Palette64       </button>65       {open && <CommandPalette onClose={() => setOpen(false)} />}66     </div>67   );68 }69 70 export default function UseScopedNavigationBasic() {71   return (72     <KeyboardProvider>73       <App />74     </KeyboardProvider>75   );76 }77

Two lists with focusWithinOnly

Preview

tsx

1 "use client";2 3 import { KeyboardProvider, useScopedNavigation } from "@diffgazer/keys";4 import { useRef } from "react";5 6 const left = ["Inbox", "Drafts", "Sent", "Archive"];7 const right = ["Today", "This week", "Later"];8 9 function getOptionId(item: string) {10   return `option-${item.toLowerCase().replace(/\s+/g, "-")}`;11 }12 13 function List({ label, items }: { label: string; items: string[] }) {14   const listRef = useRef<HTMLDivElement>(null);15 16   // focusWithinOnly: arrow keys only drive the list whose focus is active, so17   // both lists coexist under one provider without an explicit scope each.18   const { highlighted, isHighlighted } = useScopedNavigation({19     containerRef: listRef,20     role: "option",21     wrap: true,22     focusWithinOnly: true,23   });24 25   return (26     <div style={{ minWidth: 140 }}>27       <h4>{label}</h4>28       <div29         ref={listRef}30         role="listbox"31         aria-label={label}32         tabIndex={0}33         aria-activedescendant={highlighted ? getOptionId(highlighted) : undefined}34         style={{ padding: 4, border: "1px solid currentColor" }}35       >36         {items.map((item) => (37           // biome-ignore lint/a11y/useFocusableInteractive: WAI-ARIA listbox pattern — options stay non-focusable; the listbox container holds focus and aria-activedescendant tracks the active option.38           <div39             key={item}40             id={getOptionId(item)}41             role="option"42             data-value={item}43             aria-selected={isHighlighted(item)}44             style={{ padding: "4px 8px", fontWeight: isHighlighted(item) ? 700 : 400 }}45           >46             {item}47           </div>48         ))}49       </div>50     </div>51   );52 }53 54 export default function UseScopedNavigationFocusWithin() {55   return (56     <KeyboardProvider>57       <div>58         <p>Tab between the two listboxes. Arrow keys move only the focused list.</p>59         <div style={{ display: "flex", gap: 24 }}>60           <List label="Folders" items={left} />61           <List label="Filters" items={right} />62         </div>63       </div>64     </KeyboardProvider>65   );66 }67

Notes

Requires KeyboardProvider

useScopedNavigation registers keys through the KeyboardProvider context. It must be used within a <KeyboardProvider> tree.

Scope-aware

Navigation bindings respect the scope stack. If a deeper scope is active, this hook's bindings are suppressed.

No onKeyDown needed

Unlike useNavigation, you do not need to wire up an onKeyDown handler. The provider handles key dispatch.

Edge cases

Missing provider. This hook asserts the provider context on mount and throws a clear error if no KeyboardProvider is present — unlike useKey, it does not silently no-op.
scope: null. Pass null to skip registration while a conditional scope is disabled, without removing the Hook call.
focusWithinOnly. Set it when several navigable regions share one page-level provider so each region only responds while it holds focus.

useNavigation — the standalone version with an onKeyDown handler.
useScope — push the scope this hook registers under.
Scopes guide — how the scope stack resolves competing bindings.

Source

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