cmdk-solid

⌘K

⌘K is a command menu SolidJS component that can also be used as an accessible combobox. You render items, it filters and sorts them automatically. ⌘K supports a fully composable API, so you can wrap items in other components or even as static JSX.

⌘K is a port for SolidJS of pacocoursey's wonderful CMDK component.

Every attempt was made to make the behavior identical. The most notable difference is the inclusion of Kobalte to provide Dialog boxes which has a slightly different API to RadixUI.

Demo and examples: https://cmdk-solid.vercel.app/

Install

pnpm install cmdk-solid

Use

import { Command } from 'cmdk-solid'

const CommandMenu = () => {
  return (
    <Command label="Command Menu">
      <Command.Input />
      <Command.List>
        <Command.Empty>No results found.</Command.Empty>

        <Command.Group heading="Letters">
          <Command.Item>a</Command.Item>
          <Command.Item>b</Command.Item>
          <Command.Separator />
          <Command.Item>c</Command.Item>
        </Command.Group>

        <Command.Item>Apple</Command.Item>
      </Command.List>
    </Command>
  )
}

Or in a dialog:

import { Command } from 'cmdk-solid'

const CommandMenu = () => {
  const [open, setOpen] = createSignal(false)

  // Toggle the menu when ⌘K is pressed
  onMount(() => {
    const down = (e: KeyboardEvent) => {
      if (e.key === 'k' && (e.metaKey || e.ctrlKey)) {
        e.preventDefault()
        setOpen((open) => !open)
      }
    }

    document.addEventListener('keydown', down)
    onCleanup(() => document.removeEventListener('keydown', down))
  })

  return (
    <Command.Dialog open={open()} onOpenChange={setOpen} label="Global Command Menu">
      <Command.Input />
      <Command.List>
        <Command.Empty>No results found.</Command.Empty>

        <Command.Group heading="Letters">
          <Command.Item>a</Command.Item>
          <Command.Item>b</Command.Item>
          <Command.Separator />
          <Command.Item>c</Command.Item>
        </Command.Group>

        <Command.Item>Apple</Command.Item>
      </Command.List>
    </Command.Dialog>
  )
}

Parts and styling

All parts forward props, including ref, to an appropriate element. Each part has a specific data-attribute (starting with cmdk-) that can be used for styling.

Command [cmdk-root]

Render this to show the command menu inline, or use Dialog to render in a elevated context. Can be controlled with the value and onValueChange props.

Note

Values are always trimmed with the trim() method.

const [value, setValue] = createSignal('apple')

return (
  <Command value={value()} onValueChange={setValue}>
    <Command.Input />
    <Command.List>
      <Command.Item>Orange</Command.Item>
      <Command.Item>Apple</Command.Item>
    </Command.List>
  </Command>
)

You can provide a custom filter function that is called to rank each item. Note that the value will be trimmed.

<Command
  filter={(value, search) => {
    if (value.includes(search)) return 1
    return 0
  }}
/>

A third argument, keywords, can also be provided to the filter function. Keywords act as aliases for the item value, and can also affect the rank of the item. Keywords are trimmed.

<Command
  filter={(value, search, keywords) => {
    const extendValue = value + ' ' + keywords.join(' ')
    if (extendValue.includes(search)) return 1
    return 0
  }}
/>

Or disable filtering and sorting entirely:

<Command shouldFilter={false}>
  <Command.List>
    <For each={filteredItems()}>{(item) => <Command.Item value={item}>{item}</Command.Item>}</For>
  </Command.List>
</Command>

You can make the arrow keys wrap around the list (when you reach the end, it goes back to the first item) by setting the loop prop:

<Command loop />

Dialog [cmdk-dialog] [cmdk-overlay]

Props are forwarded to Command. Composes Kobalte's Dialog component. The overlay is always rendered. See the Kobalte Documentation for more information. Can be controlled with the open and onOpenChange props.

const [open, setOpen] = createSignal(false)

return (
  <Command.Dialog open={open()} onOpenChange={setOpen}>
    ...
  </Command.Dialog>
)

You can provide a container prop that accepts an HTML element that is forwarded to Kobalte's Dialog Portal component to specify which element the Dialog should portal into (defaults to body). See the SolidJS Documentation for more information.

let containerElement: HTMLDivElement | undefined

return (
  <>
    <Command.Dialog container={containerElement.current} />
    <div ref={containerElement} />
  </>
)

Input [cmdk-input]

All props are forwarded to the underlying input element. Can be controlled with the value and onValueChange props.

const [search, setSearch] = createSignal('')

return <Command.Input value={search()} onValueChange={setSearch} />

List [cmdk-list]

Contains items and groups. Animate height using the --cmdk-list-height CSS variable.

[cmdk-list] {
  min-height: 300px;
  height: var(--cmdk-list-height);
  max-height: 500px;
  transition: height 100ms ease;
}

To scroll item into view earlier near the edges of the viewport, use scroll-padding:

[cmdk-list] {
  scroll-padding-block-start: 8px;
  scroll-padding-block-end: 8px;
}

Item [cmdk-item] [data-disabled?] [data-selected?]

Item that becomes active on pointer enter. You should provide a unique value for each item, but it will be automatically inferred from the .textContent.

<Command.Item
  onSelect={(value) => console.log('Selected', value)}
  // Value is implicity "apple" because of the provided text content
>
  Apple
</Command.Item>

You can also provide a keywords prop to help with filtering. Keywords are trimmed.

<Command.Item keywords={['fruit', 'apple']}>Apple</Command.Item>

<Command.Item
  onSelect={(value) => console.log('Selected', value)}
  // Value is implicity "apple" because of the provided text content
>
  Apple
</Command.Item>

You can force an item to always render, regardless of filtering, by passing the forceMount prop.

Group [cmdk-group] [hidden?]

Groups items together with the given heading ([cmdk-group-heading]).

<Command.Group heading="Fruit">
  <Command.Item>Apple</Command.Item>
</Command.Group>

Groups will not unmount from the DOM, rather the hidden attribute is applied to hide it from view. This may be relevant in your styling.

You can force a group to always render, regardless of filtering, by passing the forceMount prop.

Separator [cmdk-separator]

Visible when the search query is empty or alwaysRender is true, hidden otherwise.

Empty [cmdk-empty]

Automatically renders when there are no results for the search query.

Loading [cmdk-loading]

You should conditionally render this with progress while loading asynchronous items.

const [loading, setLoading] = createSignal(false)

return (
  <Command.List>
    <Show when={loading()}>
      <Command.Loading>Hang on…</Command.Loading>
    </Show>
  </Command.List>
)

useCommandState(state => state.selectedField)

Hook that can return a slice of the command menu state to re-render when that slice changes. This hook is provided for advanced use cases and should not be commonly used.

A good use case would be to render a more detailed empty state, like so:

const search = useCommandState((state) => state.search)
return <Command.Empty>No results found for "{search()}".</Command.Empty>

Examples

Code snippets for common use cases.

Nested items

Often selecting one item should navigate deeper, with a more refined set of items. For example selecting "Change theme…" should show new items "Dark theme" and "Light theme". We call these sets of items "pages", and they can be implemented with simple state:

const [search, setSearch] = createSignal('')
const [pages, setPages] = createSignal<string[]>([])
const page = () => pages()[pages().length - 1]

return (
  <Command
    onKeyDown={(e) => {
      // Escape goes to previous page
      // Backspace goes to previous page when search is empty
      if (e.key === 'Escape' || (e.key === 'Backspace' && !search())) {
        e.preventDefault()
        setPages((pages) => pages.slice(0, -1))
      }
    }}
  >
    <Command.Input value={search()} onValueChange={setSearch} />
    <Command.List>
      <Show when={!page()}>
        <Command.Item onSelect={() => setPages([...pages(), 'projects'])}>Search projects…</Command.Item>
        <Command.Item onSelect={() => setPages([...pages(), 'teams'])}>Join a team…</Command.Item>
      </Show>

      <Show when={page() === 'projects'}>
        <Command.Item>Project A</Command.Item>
        <Command.Item>Project B</Command.Item>
      </Show>

      <Show when={page() === 'teams'}>
        <Command.Item>Team 1</Command.Item>
        <Command.Item>Team 2</Command.Item>
      </Show>
    </Command.List>
  </Command>
)

Show sub-items when searching

If your items have nested sub-items that you only want to reveal when searching, render based on the search state:

const SubItem = (props: CommandItemProps) => {
    const search = useCommandState(state => state.search)
    return (
      <Show when={!search()}>
        <Command.Item {...props} />
      </Show>
    )
  }

  return (
    <Command>
      <Command.Input />
      <Command.List>
        <Command.Item>Change theme…</Command.Item>
        <SubItem>Change theme to dark</SubItem>
        <SubItem>Change theme to light</SubItem>
      </Command.List>
    </Command>
  )
}

Asynchronous results

Render the items as they become available. Filtering and sorting will happen automatically.

const [loading, setLoading] = createSignal(false)
const [items, setItems] = createSignal<string[]>([])

onMount(() => {
  async function getItems() {
    setLoading(true)
    const res = await asyncResource()
    setItems(res)
    setLoading(false)
  }

  getItems()
})

return (
  <Command>
    <Command.Input />
    <Command.List>
      <Show when={loading()}>
        <Command.Loading>Fetching words…</Command.Loading>
      </Show>
      <For each={items()}>{(item) => <Command.Item value={item}>{item}</Command.Item>}</For>
    </Command.List>
  </Command>
)

Use inside Popover

We recommend using the Kobalte popover component. ⌘K relies on the Kobalte Dialog component, so this will reduce your bundle size a bit due to shared dependencies.

$ pnpm install @kobalte/core

Render Command inside of the popover content:

import { Popover } from '@kobalte/core'

return (
  <Popover.Root>
    <Popover.Anchor>
      <Popover.Trigger>Toggle popover</Popover.Trigger>
    </Popover.Anchor>

    <Popover.Portal>
      <Popover.Content>
        <Command>
          <Command.Input />
          <Command.List>
            <Command.Item>Apple</Command.Item>
          </Command.List>
        </Command>
      </Popover.Content>
    </Popover.Portal>
  </Popover.Root>
)

Drop in stylesheets

You can find global stylesheets to drop in as a starting point for styling. See website/src/styles/cmdk for examples.

FAQ

Accessible? Yes. Labeling, aria attributes, and DOM ordering tested with Voice Over and Chrome DevTools. Dialog composes an accessible Dialog implementation.

Virtualization? Performance has not been thoroughly tested. If you experience problems with performance with less than 2,000 items create a github issue. You can also roll your own virtualisation using the shouldFilter property.

Filter/sort items manually? Yes. Pass shouldFilter={false} to Command. Better memory usage and performance. Bring your own virtualization this way.

Unstyled? Yes, use the listed CSS selectors.

Hydration mismatch? This may be a bug in your code. Feel free to create an issue in this repo if you are sure it is not.

Weird/wrong behavior? Make sure your Command.Item has a unique value.

Solid Start server component? Solid Start is still in beta. On the server this component renders a full list and then applies filtering and sorting when hydration is completed.

Listen for ⌘K automatically? No, do it yourself to have full control over keybind context.

History

Refer to the original repo for the history of CMDK.

Testing

First, install dependencies and Playwright browsers:

pnpm install
pnpm playwright install

Then ensure you've built the library:

pnpm build

Then run the tests using your local build against real browser engines:

pnpm test