Menu List · paneui

Focus stays in the input.

Installation

pnpm dlx shadcn@latest add @paneui/menu-list

Usage

import { MenuList, MenuListItem, type MenuListHandle } from "@/components/ui/menu-list"

const list = React.useRef<MenuListHandle>(null)

<Input onKeyDown={(e) => list.current?.onKeyDown(e) && e.preventDefault()} />
<MenuList ref={list} aria-label="Blocks">
  <MenuListItem value="text" onSelect={() => insert("text")}>Text</MenuListItem>
  <MenuListItem value="h1" onSelect={() => insert("h1")}>Heading 1</MenuListItem>
</MenuList>

Composition

MenuList
├── MenuListGroup
│   ├── MenuListLabel
│   └── MenuListItem
│       ├── MenuListItemText
│       └── MenuListShortcut
├── MenuListSeparator
└── MenuListEmpty

Examples

Plain

Menu moves focus into its popup. Slash menus, mention pickers and autocomplete need focus to stay in the text, so MenuList tracks a highlighted value and exposes it with aria-activedescendant. The block and email editors use it for / and {{.

Keyboard

ref.current.onKeyDown(event) handles ArrowUp / ArrowDown (looping), Home / End, and Enter / Tab (clicks the highlighted item); it returns true when it used the key. The highlight resets to the first item when the list changes under it.

API Reference

MenuList

Also accepts every prop of div.

ref: React.Ref<MenuListHandle>; { onKeyDown(event): boolean, move(delta), select(): boolean }.
variant= "popup": "popup" | "plain"; popup is the menu surface (rounded-xl, p-1, max-height 320px, scrolls).
activeValue: string; Controlled highlighted item.
defaultActiveValue: string; Initial highlight (else the first item).
onActiveValueChange: (value: string) => void; Called as the highlight moves.
loop= true: boolean; Wrap from the last item to the first.

Prop	Type	Default	Description
ref	React.Ref<MenuListHandle>	—	`{ onKeyDown(event): boolean, move(delta), select(): boolean }`.
variant	"popup" \| "plain"	"popup"	`popup` is the menu surface (`rounded-xl`, `p-1`, max-height 320px, scrolls).
activeValue	string	—	Controlled highlighted item.
defaultActiveValue	string	—	Initial highlight (else the first item).
onActiveValueChange	(value: string) => void	—	Called as the highlight moves.
loop	boolean	true	Wrap from the last item to the first.

MenuListItem