Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/dip/cmdk/llms.txt

Use this file to discover all available pages before exploring further.

Command.Dialog wraps Command in a Radix UI Dialog, giving you a modal overlay without writing the boilerplate yourself. All props accepted by Command are also accepted by Command.Dialog and forwarded directly to the inner Command component. 
import { Command } from 'cmdk'

export function CommandMenu() {
  const [open, setOpen] = React.useState(false)

  React.useEffect(() => {
    const down = (e: KeyboardEvent) => {
      if (e.key === 'k' && (e.metaKey || e.ctrlKey)) {
        e.preventDefault()
        setOpen((open) => !open)
      }
    }
    document.addEventListener('keydown', down)
    return () => document.removeEventListener('keydown', down)
  }, [])

  return (
    <Command.Dialog open={open} onOpenChange={setOpen} label="Global Command Menu">
      <Command.Input placeholder="Type a command or search..." />
      <Command.List>
        <Command.Empty>No results found.</Command.Empty>
        <Command.Group heading="Suggestions">
          <Command.Item>Calendar</Command.Item>
          <Command.Item>Search</Command.Item>
          <Command.Item>Settings</Command.Item>
        </Command.Group>
      </Command.List>
    </Command.Dialog>
  )
}
Data attributes: [cmdk-dialog] on the dialog content, [cmdk-overlay] on the backdrop overlay.
The overlay is always rendered when the dialog is open. Style it with [cmdk-overlay] in your CSS.

​
Props

Command.Dialog accepts all props from Command plus the following dialog-specific props:
​
open
boolean
Controls whether the dialog is open. Use together with onOpenChange for controlled state.
​
onOpenChange
(open: boolean) => void
Callback fired when the open state changes. Receives the new open state.
​
overlayClassName
string
A className applied to the dialog overlay element ([cmdk-overlay]). Use this to apply Tailwind classes or other class-based styles to the backdrop.
​
contentClassName
string
A className applied to the dialog content element ([cmdk-dialog]). Use this to position and size the modal panel.
​
container
HTMLElement
An HTML element to portal the dialog into. Forwarded to Radix’s Dialog Portal. Defaults to document.body.
The following props from Command are also accepted and forwarded:
​
label
string
Accessible label for the command menu. Sets aria-label on the dialog content.
​
shouldFilter
boolean
default:"true"
Set to false to disable automatic filtering and sorting.
​
filter
(value: string, search: string, keywords?: string[]) => number
Custom filter function for ranking items against the search query.
​
defaultValue
string
The initially selected item value.
​
value
string
Controlled value of the selected item.
​
onValueChange
(value: string) => void
Callback fired when the selected item changes.
​
loop
boolean
default:"false"
Enable wrap-around keyboard navigation.
​
disablePointerSelection
boolean
default:"false"
Disable selecting items by pointer movement.
​
vimBindings
boolean
default:"true"
Enable Ctrl+N/J/P/K navigation shortcuts.

​
Examples

​
Open and close with state

Toggle the dialog using a useState boolean. Bind a keyboard shortcut to open it: 
const [open, setOpen] = React.useState(false)

React.useEffect(() => {
  const down = (e: KeyboardEvent) => {
    if (e.key === 'k' && (e.metaKey || e.ctrlKey)) {
      e.preventDefault()
      setOpen((open) => !open)
    }
  }
  document.addEventListener('keydown', down)
  return () => document.removeEventListener('keydown', down)
}, [])

return (
  <Command.Dialog open={open} onOpenChange={setOpen}>
    <Command.Input />
    <Command.List>
      <Command.Item>Calendar</Command.Item>
      <Command.Item>Settings</Command.Item>
    </Command.List>
  </Command.Dialog>
)

​
Custom portal container

By default the dialog portals into document.body. Pass a container ref to portal into a specific element instead: 
const containerRef = React.useRef<HTMLDivElement>(null)

return (
  <>
    <Command.Dialog
      open={open}
      onOpenChange={setOpen}
      container={containerRef.current ?? undefined}
    >
      <Command.Input />
      <Command.List>
        <Command.Item>Apple</Command.Item>
      </Command.List>
    </Command.Dialog>

    {/* The dialog will portal into this element */}
    <div ref={containerRef} />
  </>
)
Ensure the open prop is false during server-side rendering to avoid hydration mismatches.

Build docs developers (and LLMs) love

Get started for freeTalk to us