useListFocus@xds/core · hooks
Preview coming soon
Usage
Manages keyboard navigation within a linear list following WAI-ARIA menu/listbox/toolbar patterns. Supports arrow key navigation (vertical or horizontal), Home/End for boundaries, optional wrap-around, and Escape to close. Suitable for dropdown menus, toolbars, and any 1D focusable list.Best practices
| Guidance | Practices |
|---|---|
| Do | Set orientation to 'horizontal' for toolbars and tab bars, 'vertical' for dropdown menus. |
| Do | Provide an onEscape callback for menus/dropdowns to return focus to the trigger. |
| Don't | Use for 2D grid navigation — prefer useGridFocus for grids and calendars. |
Parameters
| Param | Type | Description |
|---|---|---|
options | UseListFocusOptions | Configuration object for list focus behavior. All fields are optional. |
options.itemSelector | string (default: '[role="menuitem"]') | Selector for focusable items within the list. |
options.wrap | boolean (default: true) | Whether arrow navigation wraps around at the ends. |
options.onEscape | () => void | Callback when Escape key is pressed (e.g., close menu). |
options.orientation | 'horizontal' | 'vertical' (default: 'vertical') | Navigation orientation. 'horizontal' uses ArrowLeft/ArrowRight, 'vertical' uses ArrowUp/ArrowDown. |
Returns
| Field | Type | Description |
|---|---|---|
| listRef | React.RefObject<HTMLElement | null> | Ref to attach to the list container element. |
| handleKeyDown | (e: React.KeyboardEvent) => void | Key down handler to attach to the list container. |
| focusItem | (index: number) => void | Focus a specific item by index (clamped to valid range). |
| focusFirst | () => void | Focus the first focusable item in the list. |
| focusLast | () => void | Focus the last focusable item in the list. |
Import
ts