Skip to content
WunderUI

useMenuKeys

Pro

Arrow keys, Enter and Escape for a menu that opens from a text field.

import { useMenuKeys } from "@wunderui/react"

Playground

Type / and a letter to filter. Arrow keys move, Enter runs the command, Escape closes the list.

index: 0 · open: false · last run: none

Installation

useMenuKeys comes with WunderUI Core and Pro, in the entry of the package from your plan. See the plans. Then import it:

tsx
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.

ts
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

ParameterTypeDescription
countnumberHow many items the list shows right now. Pass the length of the filtered list, not of the full one. With no key is handled.
options.openbooleanWhether the list is on screen. The keys act only while it is ; otherwise typing and arrows work as in any field.
options.onEnter(index: number) => voidCalled with the highlighted index when Enter is pressed. Run the command or insert the mention here.
options.onEscape optional(() => void) | undefinedCalled when Escape is pressed. Close the list here. Escape is swallowed while the list is open, whether you pass this or not.

Returns

An object with the highlighted index, a setter for it and the keydown handler.

FieldTypeDescription
indexnumberThe highlighted item, counted from . It starts at and goes back to whenever or changes.
setIndexReact.Dispatch<React.SetStateAction<number>>Sets the highlight yourself, usually from a hover handler so the pointer and the arrow keys share one marker.
onKeyDown(e: React.KeyboardEvent) => voidPut it on the field that owns focus, the textarea or input, as its .

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.

MCPget_component("useMenuKeys")
Importimport { useMenuKeys } from "@wunderui/react"

The full library index for assistants is at /llms.txt.