useMenuKeys
Arrow keys, Enter and Escape for a menu that opens from a text field.
import { useMenuKeys } from "@wunderui/react"Playground
Installation
useMenuKeys comes with WunderUI Core and Pro, in the entry of the package from your plan. See the plans. Then import it:
import { useMenuKeys } from "@wunderui/react"When to use
Use useMenuKeys for
- A list that opens under a text field while focus stays in the field: slash commands, mentions, suggestions.
- Your own listbox next to a field, with pointing at the highlighted option.
Use something else for
- SlashCommandMenu for the ready-made command list that this hook drives.
- MentionPicker for the ready-made @ picker, driven the same way.
- Combobox for a field whose value is picked from a list. It handles its own keys and focus.
- Autocomplete for a text field that suggests values while you type, with its own keys.
- Dropdown Menu for a menu that a button opens and that takes focus itself.
Signature
For a list that opens under a prompt, such as slash commands or mentions, while focus stays in the textarea. The hook returns the highlighted , a setter, and an handler for the field. It handles four keys and leaves every other key, such as Home, End and typing, to the field.
useMenuKeys(count: number, options: { open: boolean; onEnter: (index: number) => void; onEscape?: () => void; }): { index: number; setIndex: React.Dispatch<React.SetStateAction<number>>; onKeyDown: (e: React.KeyboardEvent) => void; }Parameters
Returns
An object with the highlighted index, a setter for it and the keydown handler.
Keyboard interactions
The handler goes on the text field. While the list is open and has items, these keys belong to the list.
- ArrowDown
- Highlights the next item. After the last one it goes back to the first. The caret does not move.
- ArrowUp
- Highlights the previous item. Before the first one it goes to the last. The caret does not move.
- Enter
- Calls with the highlighted index. The key does not add a line break.
- ShiftEnter
- Not handled. It adds a line break as in any textarea.
- Escape
- Calls . The key is swallowed () but still bubbles, also when you pass no .
Home, End, Page Up, Page Down, Tab and typing are not handled: they work in the field as usual, so the caret moves and the text changes. There is no type-ahead; the list filters by what you type, which is up to you.
Behavior and motion
The hook keeps one number and one handler. The menu, the filtering and the ARIA wiring stay in your component.
- State
- starts at . It goes back to after a render in which or changed, so opening the list or narrowing it by typing starts again at the top. If the filter swaps items but the count stays the same, the index stays where it was.
- When keys act
- Only while is and is above . In every other case the handler returns at once and the key reaches the field untouched, so a closed or empty list never swallows an arrow key or Enter.
- Input methods
- An Enter that confirms an IME composition (Japanese, Chinese, Korean input) belongs to the composition and does not reach . Shift+Enter is ignored, so it still adds a line.
- Not included
- The hook does not scroll the highlighted item into view, does not set and does not close the list when the field loses focus. Do those in your component.
- Server rendering
- The hook only holds state and returns a handler, and it touches neither nor , so it renders on the server and hydrates without a mismatch.
- Cleanup
- There are no listeners to remove: the handler is a normal React . It is a new function on every render, so memoize it only if the field is memoized.
- Motion
- The hook does not animate. The highlight changes at once; if you fade the marker, animate or with and .
- Reduced motion
- Nothing in the hook depends on . A highlight that moves with a transform of your own needs a fallback.
Best practices
- Do
Pass the length of the filtered list as . A count that is larger than the visible list highlights an item that is not there.
- Do
Keep focus in the field and point at the highlighted option, with and on a single-line . A cannot take the combobox role: give it , and instead.
- Do
Keep and the visible list in step. is only while the list is on screen.
- Don’t
Do not rely on the hook for Home, End or type-ahead. It does not handle them; build them in your own if the list needs them.
- Do
Give mouse and keyboard one marker: call on hover, and prevent on the options so the field keeps focus.
- Don’t
Do not put a second on the same field that also handles Enter. Call yours first and return when is set.
- Do
Scroll the highlighted option into view yourself in a long list, with .
Notes for AI
Give your coding assistant the page or the MCP call instead of screenshots.
get_component("useMenuKeys")import { useMenuKeys } from "@wunderui/react"The full library index for assistants is at /llms.txt.