cmdk

What is cmdk?

cmdk is a React component library for building command menus. It provides a flexible and customizable way to create command palettes, similar to those found in applications like VSCode, Figma, and Notion.

What are cmdk's main functionalities?

Basic Command Menu

This code demonstrates how to create a basic command menu using cmdk. It includes an input field for typing commands and a list of command items.

import { Command } from 'cmdk';

function App() {
  return (
    <Command>
      <Command.Input placeholder="Type a command or search..." />
      <Command.List>
        <Command.Item>First Command</Command.Item>
        <Command.Item>Second Command</Command.Item>
      </Command.List>
    </Command>
  );
}

Nested Command Menus

This code demonstrates how to create nested command menus using cmdk. It shows how to include a sub-menu within a command item.

import { Command } from 'cmdk';

function App() {
  return (
    <Command>
      <Command.Input placeholder="Type a command or search..." />
      <Command.List>
        <Command.Item>First Command</Command.Item>
        <Command.Item>Second Command</Command.Item>
        <Command.Item>
          Nested Menu
          <Command.List>
            <Command.Item>Nested Command 1</Command.Item>
            <Command.Item>Nested Command 2</Command.Item>
          </Command.List>
        </Command.Item>
      </Command.List>
    </Command>
  );
}

Custom Styling

This code demonstrates how to apply custom styling to the command menu and its elements using CSS classes.

import { Command } from 'cmdk';
import './App.css';

function App() {
  return (
    <Command className="custom-command">
      <Command.Input className="custom-input" placeholder="Type a command or search..." />
      <Command.List className="custom-list">
        <Command.Item className="custom-item">First Command</Command.Item>
        <Command.Item className="custom-item">Second Command</Command.Item>
      </Command.List>
    </Command>
  );
}

Other packages similar to cmdk

react-aria

react-aria is a library that provides accessible UI primitives for React applications. It includes hooks and components for building accessible command menus, among other UI elements. Compared to cmdk, react-aria offers a broader range of accessibility-focused components but may require more setup for command menus.

downshift

downshift is a library for building flexible, enhanced input components in React. It can be used to create command menus, dropdowns, and other input-related components. While downshift provides more flexibility and control, it may require more boilerplate code compared to cmdk.

react-select

react-select is a flexible and customizable select input control for React. It can be adapted to create command menus with search functionality. However, react-select is primarily designed for select inputs and may not offer the same level of command menu-specific features as cmdk.

README

Command

Command • CommandInput • CommandList • CommandItem • useCommand

At the simplest, a Command looks like this:

const Example = () => {
  const commandProps = useCommand()

  return (
    <Command
      aria-label="Command menu"
      dialog={false}
      {...commandProps}
    >
      <CommandInput />
      <CommandList>
        <CommandItem value="No Priority">No Priority</CommandItem>
        <CommandItem value="Urgent">Urgent</CommandItem>
        <CommandItem value="High">High</CommandItem>
        <CommandItem value="Medium">Medium</CommandItem>
        <CommandItem value="Low">Low</CommandItem>
      </CommandList>
    </Command>
  )
}

Installation

yarn add colist

import {
	Command,
	CommandInput,
	CommandList,
	CommandItem,
	useCommand
} from 'colist'

Command

CSS selector: data-command and optionally data-command-overlay

Required props: Pass it everything returned from useCommand.

Optional props:

• className (string): class applied to the wrapper node
• dialog (boolean): whether to render the Command in a dialog
• overlayClassName (string): if rendered in a dialog, the class of the overlay
• aria-label (string): if rendered in a dialog, the label of the dialog
• onDismiss (function): if rendered in a dialog, the callback function when closed
• ordering (boolean): whether to automatically order items

CommandInput

Must be rendered inside a <Command>.

CSS selector: data-command-input

Required props: None.

Optional props: Any props will be spread to the <input /> element. Also forwards ref.

CommandList

Must be rendered inside a <Command>.

CSS selector: data-command-list and data-command-list-empty

Required props: None.

Optional props: Any props will be spread to the <ul /> element. Also forwards ref.

CommandItem

Must be rendered inside a <CommandList>

CSS selector: data-command-item and aria-selected when active

Required props:

• value (string): string to compare against for filtering and ordering

Optional props:

• callback (function): what to execute on click or selection

All other props will be made available on commandProps.map.current

useCommand

const commandProps = useCommand(defaults)

Automatically handles all logic and state for efficiently rendering, filtering, and ordering items.

defaults

• search = '' (string): initial value of the <CommandInput>
• selected = 0 (number): index of initially selected item
• open = false (boolean): if rendered as a dialog, initially open or not
• items = [] (any[]): an array of items that represent subsequent screens
• ordering = true (boolean): whether to automatically filter and order items

Return Value (commandProps)

• items (any[]): an array of items that represent subsequent screens
• search (string): value of the input
• open (boolean): if rendered as a dialog, the open state
• selected (number): index of currently selected item
• setSelected (function): update currently selected item
• list (ref): list.current is an array of all visible items
• map (ref): map.current is a Map of all items and their associated props