useCommandMenu

Hook that manages a searchable command palette with filtered options, keyboard navigation, and grouped items.

Navigate↵Select

basic-demo

Usage#

import { useCommandMenu } from '@primereact/headless/commandmenu';
 
const commandmenu = useCommandMenu({
    options: commands,
    optionLabel: 'label',
    optionValue: 'value',
    optionGroupLabel: 'group',
    optionGroupChildren: 'items'
});
 
return (
    <div {...commandmenu.rootProps}>
        <input {...commandmenu.inputProps} />
        <ul {...commandmenu.listProps}>
            {commandmenu.filteredOptions.map((item, index) => (
                <li {...commandmenu.getItemProps(item, index)}></li>
            ))}
        </ul>
    </div>
);

useCommandMenu manages search filtering, keyboard navigation, and item selection for a command palette — see Primitive for a component-based API.

Features#

rootProps, inputProps, listProps, and groupProps provide spread-ready prop objects for each DOM element
getItemProps(option, index) returns ARIA attributes, selection state, and event handlers per item
filteredOptions and filteredCount expose the current search-filtered results
setSearch(value) programmatically updates the search query
Custom filter function support with numeric scoring for ranked results

Behavior#

Grouped Options#

Define optionGroupLabel and optionGroupChildren to organize items into groups. Groups are automatically filtered and sorted by their highest-scoring child.

const commandmenu = useCommandMenu({
    options: groupedCommands,
    optionLabel: 'label',
    optionGroupLabel: 'group',
    optionGroupChildren: 'items'
});

Custom Filter#

Pass a filter function that returns a numeric score. Higher scores rank higher; 0 means no match.

const commandmenu = useCommandMenu({
    options: commands,
    optionLabel: 'label',
    filter: (label, search) => {
        if (label.toLowerCase().startsWith(search.toLowerCase())) return 2;
        if (label.toLowerCase().includes(search.toLowerCase())) return 1;
        return 0;
    }
});

Keywords#

Set optionKeywords to include additional search terms per option. The default filter matches against both the label and keyword fields.

const commandmenu = useCommandMenu({
    options: commands,
    optionLabel: 'label',
    optionKeywords: 'keywords'
});

Controlled Search#

Pass search with onSearchChange for controlled search state.

const [search, setSearch] = React.useState('');
 
const commandmenu = useCommandMenu({
    options: commands,
    optionLabel: 'label',
    search,
    onSearchChange: (e) => setSearch(e.query)
});

Set loop to true to wrap keyboard navigation from the last item back to the first.

const commandmenu = useCommandMenu({
    options: commands,
    optionLabel: 'label',
    loop: true
});

Item Selection#

Use onItemSelect to handle item selection triggered by Enter key or click.

const commandmenu = useCommandMenu({
    options: commands,
    optionLabel: 'label',
    onItemSelect: (e) => console.log(e.value)
});

Custom Styling with Data Attributes#

[data-scope='commandmenu'][data-part='root'] { ... }
[data-scope='commandmenu'][data-part='item'][data-selected] {
    background: #f5f5f5;
}
[data-scope='commandmenu'][data-part='item'][data-disabled] {
    opacity: 0.5;
    pointer-events: none;
}

API#

useCommandMenu#

Name	Type	Default
`options`	`unknown[]`	—
An array of options to display in the command menu.
`optionLabel`	`string`	—
Property name to use as the display label for options.
`optionValue`	`string`	—
Property name to use as the value for options.
`optionDisabled`	`string`	—
Property name to check if an option is disabled.
`optionGroupLabel`	`string`	—
Property name for the group label when using grouped options.
`optionGroupChildren`	`string`	—
Property name for the group children when using grouped options.
`optionKeywords`	`string`	—
Property name for keywords array on option objects (used for search matching).
`search`	`string`	—
The controlled search value.
`defaultSearch`	`string`	—
The default search value for uncontrolled mode.
`onSearchChange`	`(event: useCommandMenuSearchChangeEvent) => void`	—
Callback fired when the search value changes.
`onItemSelect`	`(event: useCommandMenuItemSelectEvent) => void`	—
Callback fired when an item is selected (via Enter key or click).
`filter`	`(label: string, search: string, keywords?: string[]) => number`	—
Custom filter/scoring function. Returns a numeric score (0 = no match, higher = better match).
`selectOnHover`	`boolean`	—
Whether to highlight items on hover.
`loop`	`boolean`	—
Whether keyboard navigation loops around from last to first item.

Accessibility#

See CommandMenu Primitive for WAI-ARIA compliance details and keyboard support.