Command Menu

Installation

Install the component via the CLI in one command.

npx shadcn@latest add @intentui/command-menu

Composed components

Manual installation

Use this approach if you prefer to install and wire up the component yourself instead of using the CLI.

npm install react-aria-components @heroicons/react tailwind-merge

Anatomy

"use client"

import {
  IconBill,
  IconCube,
  IconGear,
  IconHome,
  IconNotes,
  IconShield,
} from "@heroicons/react"
import { useState } from "react"
import { Button } from "@/components/ui/button"
import {
  CommandMenu,
  CommandMenuItem,
  CommandMenuShortcut,
  CommandMenuLabel,
  CommandMenuList,
  CommandMenuSearch,
  CommandMenuSection,
} from "@/components/ui/command-menu"

export function CommandPalette() {
  const [isOpen, setIsOpen] = useState(false)
  return (
    <>
      <Button intent="outline" onPress={() => setIsOpen(true)}>
        Open
      </Button>
      <CommandMenu isOpen={isOpen} onOpenChange={setIsOpen}>
        <CommandMenuSearch placeholder="Quick search..." />
        <CommandMenuList>
          <CommandMenuSection label="Pages">
            <CommandMenuItem textValue="Home" href="#">
              <IconHome />
              <CommandMenuLabel>Home</CommandMenuLabel>
            </CommandMenuItem>
            <CommandMenuItem textValue="Docs" href="#">
              <IconNotes />
              <CommandMenuLabel>Docs</CommandMenuLabel>
              <CommandMenuShortcut>⌘k</CommandMenuShortcut>
            </CommandMenuItem>
            <CommandMenuItem textValue="Components" href="#">
              <IconCube />
              <CommandMenuLabel>Components</CommandMenuLabel>
            </CommandMenuItem>
          </CommandMenuSection>
          <CommandMenuSection label="Dashboard">
            <CommandMenuItem textValue="billing" href="#">
              <IconBill />
              <CommandMenuLabel>Billing</CommandMenuLabel>
            </CommandMenuItem>
            <CommandMenuItem textValue="settings" href="#">
              <IconGear />
              <CommandMenuLabel>Settings</CommandMenuLabel>
              <CommandMenuShortcut>⌘s</CommandMenuShortcut>
            </CommandMenuItem>
            <CommandMenuItem textValue="security" href="#">
              <IconShield />
              <CommandMenuLabel>Security</CommandMenuLabel>
            </CommandMenuItem>
          </CommandMenuSection>
        </CommandMenuList>
      </CommandMenu>
    </>
  )
}

Examples

Separator

Creating a separator is super simple, just use CommandMenuSeparator. However, make sure to place it within a CommandMenuSection for proper structure.

Keyboard

Integrate keyboard interaction with the command menu. Note that keyboard functionality may be limited on smaller screens.

Trigger by keyboard

Activate the command menu via keyboard commands, ideal for initiating command palettes.

Danger

Highlight a command item as dangerous by changing its color to red, indicating a warning.

Controlled

Dynamically manage the command palette with the inputValue and onInputChange props, ensuring it stays responsive to updates from the parent component. Additionally, ensure each CommandMenuItem includes a textValue prop, enabling seamless item filtering through the search input.

Additionally, control the execution of an action upon selecting an item:

<CommandItem onAction={() => console.log('share intentui.com/d/command')} />

Pending

The isPending prop can be used to indicate that the command menu is loading data. This can be useful when you need to display a loading indicator while the data is being fetched.

Disabled

Disable items in the command menu to make them non-interactive, appearing grayed out.

Hide escape button

To hide the escape button, set escapeButton to false. View this setup in the Command Description section.

<CommandMenu
  escapeButton={false}
  isOpen={isOpen}
  onOpenChange={setIsOpen}
/>

Description

Enhance command items with descriptions using the CommandDescription component. Be aware that keyboard accessibility might be limited on smaller screens.

Hide scrollbar

To hide the scrollbar, set className to scrollbar-none. But before you do that, make sure to add this snippet into your css file.

@utility scrollbar-none {
  -ms-overflow-style: none; /* Internet Explorer and Edge */
  scrollbar-width: none; /* Firefox */
  &::-webkit-scrollbar {
    display: none; /* Safari and Chrome */
  }
}

<CommandMenuList className="scrollbar-none">

Navigating

Indeed, when using this command palette within client-side frameworks like Next.js or Inertia.js, it’s practical to automatically close the palette upon navigating via a link. Here’s how you can manage that:

Inertia.js

In Inertia.js, utilize the router.on('navigate') event to automatically close the command palette when navigation occurs. Here’s an example: This setup ensures that the command palette closes seamlessly when the user navigates to a new page, maintaining a clean and distraction-free user interface.

export function CommandPalette({ open, setOpen }: Props) {
  useEffect(() => {
    router.on('navigate', () => setOpen(false))
  }, [pathname, setOpen])
  return (...)

Next.js

When using Next.js, you can use the usePathname hook to close the command palette when you navigate to a new page.

export function CommandPalette({ open, setOpen }: Props) {
  const pathname = usePathname()

  useEffect(() => {
    setOpen(false)
  }, [pathname])
  return (...)

On action

To close the command palette when an action is performed, use the onAction prop. This prop accepts a callback function that is called when an action is performed. The callback function receives the action object as an argument.

<CommandMenu
  onAction={(action) => {
    if (action.type === 'close') {
      setIsOpen(false)
    }
  }}
/>

Component API

CommandMenu

The CommandMenu component displays a searchable command palette.

CommandMenuDescription

The CommandMenuDescription component renders secondary text for a command item.

CommandMenuFooter

The CommandMenuFooter component renders footer content inside the command menu.

CommandMenuItem

The CommandMenuItem component represents one command menu action.

CommandMenuLabel

The CommandMenuLabel component renders the primary text for a command item.

CommandMenuList

The CommandMenuList component contains command menu items.

CommandMenuSearch

The CommandMenuSearch component renders the command menu search input.

CommandMenuSection

The CommandMenuSection component groups related command menu items.

CommandMenuSeparator

The CommandMenuSeparator component separates command menu groups.

CommandMenuShortcut

The CommandMenuShortcut component displays a keyboard shortcut for a command item.

See the React Aria for the full API reference.