Parameters

Name	Type	Default	Description
options	UseListFocusOptions	{}	Configuration object for the list focus behavior. All fields are optional.
options.itemSelector	string	'[role="menuitem"]'	Selector for the focusable items within the list.
options.boundarySelector	string	—	Selector identifying a list boundary, for lists that contain nested lists of the same kind (e.g. a menu with submenu flyouts). When set, item collection and key handling are scoped to this level's own container. Typically '[role="menu"]'.
options.wrap	boolean	true	Whether arrow navigation wraps around at the ends.
options.onEscape	() => void	—	Callback when Escape is pressed (e.g. close the menu). Supplying it also consumes the key (preventDefault); without it Escape passes through to the surrounding layer.
options.orientation	'horizontal' | 'vertical' | 'both'	'vertical'	Navigation orientation. 'horizontal' uses ArrowLeft/ArrowRight, 'vertical' uses ArrowUp/ArrowDown, 'both' accepts all four arrows. A horizontal list follows the container's writing direction, so RTL swaps the two arrow keys.
options.hasHomeEnd	boolean	true	Whether Home/End jump to the first/last enabled item.
options.hasPaging	boolean	false	Whether PageDown/PageUp page through a scrolling list: PageDown moves to the last enabled item fully visible in the container, and pressed there again one viewport further; PageUp mirrors it. Neither wraps; in a list that does not scroll they act as End/Home.
options.hasRovingTabIndex	boolean	false	Opt into roving-tabindex ownership: the hook stamps a single tab stop (one item tabindex="0", the rest -1), repairs it as items mount, unmount, or toggle disabled, and moves it with arrow navigation. When false, the hook only moves focus and never touches tabindex.
options.hasCaretGuard	boolean	false	When true, arrow keys are not stolen from a nested text input/textarea whose caret is not at the boundary in the direction of travel (or that has a selection), and are never stolen from a nested contenteditable. Preserves inline text editing within the list.

Returns

Name	Type	Description
listRef	Ref<HTMLElement | null>	Bind to the list container element.
handleKeyDown	(event: KeyboardEvent) => void	Key down handler to attach to the list container.
handleFocus	(event: FocusEvent) => void	Focus handler for the container. Keeps the roving tab stop in sync when hasRovingTabIndex is enabled; a no-op otherwise, so it is always safe to attach.
focusItem	(index: number) => void	Focus a specific item by index, clamped to the valid range.
focusFirst	() => boolean	Focus the first enabled item. Returns true when an item was focused.
focusLast	() => boolean	Focus the last enabled item. Returns true when an item was focused.
ownsEvent	(event: KeyboardEvent) => boolean	Whether a key event belongs to this list level rather than a nested list sharing the same boundarySelector. Always true when no boundarySelector is set. Use it to guard consumer-added key handling (Enter/Space, typeahead).
getItems	() => HTMLElement[]	This level's focusable items in DOM order, already scoped by boundarySelector and with hidden ones dropped. Build typeahead targets from this instead of re-querying.