CommandMenu

An unstyled searchable command palette with grouped items and keyboard navigation.

Build fully custom command palettes with complete control over layout and styling.

basic-demo

Pre-styled Versions

Choose a pre-styled library to use CommandMenu with ready-made designs.

Styled

Theme-based styling with CSS variables

Tailwind

Utility-first styling with Tailwind CSS

For hook-based usage without components, see the Headless API.

Features#

Compound component API with sub-components: Root, Header, Input, List, Item, Group, GroupHeader, Footer, Empty
Score-based filtering with support for custom filter functions and keyword matching
Grouped option rendering with automatic group filtering and sorting by relevance
Auto-focus management with scroll-into-view for the active item

Usage#

import { CommandMenu } from 'primereact/commandmenu';

<CommandMenu>
    <CommandMenu.Input />
    <CommandMenu.Empty></CommandMenu.Empty>
    <CommandMenu.List>
        <CommandMenu.Group>
            <CommandMenu.GroupHeading></CommandMenu.GroupHeading>
            <CommandMenu.Item></CommandMenu.Item>
        </CommandMenu.Group>
    </CommandMenu.List>
</CommandMenu>

Behavior#

Polymorphic Rendering#

Use as on any sub-component to change the rendered HTML element.

<CommandMenu.Root as="section">...</CommandMenu.Root>

Render Function Children#

CommandMenu.List accepts a render function providing access to the command menu instance.

<CommandMenu.List>{({ commandmenu }) => <div>{commandmenu.filteredCount} results</div>}</CommandMenu.List>

Pass Through#

Some parts may not be visible in the preview depending on the component's current state.

/* Select a part to see its CSS selector for custom styling */

API#

CommandMenuRoot#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: CommandMenuRootInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: CommandMenuRootInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`CommandMenuRootInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<CommandMenuRootPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: CommandMenuRootInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`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.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-scope`	`"commandmenu"`
`data-part`	`"root"`

Defines passthrough(pt) options of CommandMenu component.

label	type	description
root	CommandMenuRootPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the root's DOM element.
list	CommandMenuRootPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the list's DOM element.
group	CommandMenuRootPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the group's DOM element.
groupheader	CommandMenuRootPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the group header's DOM element.
item	CommandMenuRootPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the item's DOM element.
empty	CommandMenuRootPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the empty's DOM element.
header	CommandMenuRootPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the header's DOM element.
footer	CommandMenuRootPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the footer's DOM element.
input	CommandMenuRootPassThroughType<HTMLAttributes<HTMLInputElement>>	Used to pass attributes to the input's DOM element.

CommandMenuInput#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: CommandMenuInputInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: CommandMenuInputInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`CommandMenuInputInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<CommandMenuInputPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: CommandMenuInputInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`value`	`string`	—
Value of the input.
`onValueChange`	`(value: string) => void`	—
Callback function that is called when the value changes.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-scope`	`"commandmenu"`
`data-part`	`"input"`

Defines passthrough(pt) options of CommandMenuInput component.

label	type	description
root	CommandMenuInputPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the root's DOM element.

CommandMenuList#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: CommandMenuListInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: CommandMenuListInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`CommandMenuListInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<CommandMenuListPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: CommandMenuListInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-scope`	`"commandmenu"`
`data-part`	`"list"`

Defines passthrough(pt) options of CommandMenuList component.

label	type	description
root	CommandMenuListPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the root's DOM element.

CommandMenuItem#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: CommandMenuItemInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: CommandMenuItemInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`CommandMenuItemInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<CommandMenuItemPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: CommandMenuItemInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`index`	`number`	—
The index of the item in the flattened options array. If not provided but `option` is, the index is resolved automatically.
`option`	`unknown`	—
The option object reference. Used to automatically resolve the flat index when `index` is not explicitly provided.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-selected`	Present when item is focused
`data-disabled`	Present when item is disabled

Defines passthrough(pt) options of CommandPaletteItem component.

label	type	description
root	CommandMenuItemPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the root's DOM element.

CommandMenuGroup#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: CommandMenuGroupInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: CommandMenuGroupInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`CommandMenuGroupInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<CommandMenuGroupPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: CommandMenuGroupInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-scope`	`"commandmenu"`
`data-part`	`"group"`

Defines passthrough(pt) options of CommandMenuGroup component.

label	type	description
root	CommandMenuGroupPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the root's DOM element.

CommandMenuGroupHeader#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: CommandMenuGroupHeaderInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: CommandMenuGroupHeaderInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`CommandMenuGroupHeaderInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<CommandMenuGroupHeaderPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: CommandMenuGroupHeaderInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Defines passthrough(pt) options of CommandMenuGroupHeader component.

label	type	description
root	CommandMenuGroupHeaderPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the root's DOM element.

CommandMenuHeader#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: CommandMenuHeaderInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: CommandMenuHeaderInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`CommandMenuHeaderInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<CommandMenuHeaderPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: CommandMenuHeaderInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Defines passthrough(pt) options of CommandMenuHeader component.

label	type	description
root	CommandMenuHeaderPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the root's DOM element.

CommandMenuFooter#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: CommandMenuFooterInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: CommandMenuFooterInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`CommandMenuFooterInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<CommandMenuFooterPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: CommandMenuFooterInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Defines passthrough(pt) options of CommandMenuFooter component.

label	type	description
root	CommandMenuFooterPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the root's DOM element.

CommandMenuEmpty#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: CommandMenuEmptyInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: CommandMenuEmptyInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`CommandMenuEmptyInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<CommandMenuEmptyPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: CommandMenuEmptyInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Defines passthrough(pt) options of CommandMenuEmpty component.

label	type	description
root	CommandMenuEmptyPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the root's DOM element.

Accessibility#

CommandMenu renders a combobox with an input (role="combobox") that controls a list of options (role="listbox"). Items use aria-selected to reflect the current selection and aria-disabled="true" when an item cannot be chosen. The accessible name can be overridden with aria-label or aria-labelledby on the root component.

Keyboard Support#

Key / Combo	Function
`ArrowDown` / `ArrowUp`	Move to next / previous item
`Home` / `End`	Move to first / last item
`Enter`	Selects the active item (ignored when disabled)