janovekj/cmdkit

Command palette component for React

🧰 cmdkit

Command palette component for React

Getting started

npm i cmdkit

Simple example

import { CommandPalette } from "cmdkit";

const logTime = {
  id: "logTime",
  name: "Log current time",
  command: () => console.log(new Date()),
  view: <p>Running this command will log the current time</p>,
};

const App = () => {
  return (
    <div>
      <CommandPalette commands={[logTime]} />
      {/* rest of the app*/}
    </div>
  );
};

Advanced example

// index.ts - outside of where `CommandPalette` is used
import { CommandEventProvider } from "cmdkit";

ReactDOM.render(
  <CommandEventProvider>
    <App />
  </CommandEventProvider>,
  document.getElementById("root")
);

// App.tsx
import { CommandPalette, useAppearEvent } from "cmdkit";

const useCounterLog = () => {
  const id = "counterLog";

  const [count, setCount] = useState(0);

  useAppearEvent(id, () => setCount((prev) => prev + 1));

  return {
    id,
    name: `Log the current time`,
    command: () => console.log(new Date()),
    view: <p>This command has appeared in the search results {count} times</p>,
  };
};

const App = () => {
  const counterLog = useCounterLog();
  return (
    <div>
      <CommandPalette commands={[counterLog]} />
      {/* rest of the app*/}
    </div>
  );
};

API Reference

Types

Command

<CommandPalette /> accepts a list of Commands, which is an object with the following properties:

• id A string that uniquely identifies the command
• name The displayed name in the command palette
• command (Optional) The function to run when the command is selected
• view (Optional) A React element to show in the pane next to the search results

import { Command } from "cmdkit";

const logTime: Command = {
  id: "logTime",
  name: "Log the current time",
  command: () => console.log(new Date()),
  view: (
    <div>
      <p>This command logs the current time</p>
    </div>
  ),
};

Components

CommandPalette

Renders a command palette in your application

• Open with ⌘ + K (Mac) or Alt + K (Windows).
• Navigate commands with up and down arrows
• Run a command by pressing Enter
• Esc to close

Accepts a list of Commands through the commands prop.

import { CommandPalette } from "cmdkit";

const App = () => (
  <div>
    <CommandPalette
      commands={[
        {
          id: "simpleCommand",
          name: "A simple command",
          command: () => console.log("That was simple!"),
        },
      ]}
    />
    <h1>My app</h1>
  </div>
);

CommandEventProvider

Manages the state of event hooks which commands can use to provide advanced functionality.

Must be used outside the component which renders the <CommandPalette /> component.

import { CommandPalette, CommandEventProvider } from "cmdkit"

const App = () => <div>
  <CommandPalette commands={...} />
  <h1>My app</h1>
</div>

const Root = () => <CommandEventProvider>
  <App />
</CommandEventProvider>

Hooks

cmdkit provides a couple of hooks for tapping into a command's life cycle.

Note: Usage of these hooks must happen within a CommandEventProvider />

useAppearEvent

Allows you to run code when the command appears in the search results. Will re-run each time the command appears.

import { useAppearEvent } from "cmdkit";

useAppearEvent("myCommand", () => console.log("just appeared!"));

useFocusEvent

Allows you to run code when the command receives focus in the search results.

import { useFocusEvent } from "cmdkit";

useFocusEvent("myCommand", () => console.log("received focus!"));

useBlurEvent

Allows you to run code when the command loses focus in the search results.

import { useFocusEvent } from "cmdkit";

useFocusEvent("myCommand", () => console.log("lost focus!"));

useExecuteEvent

Allows you to run additional code when a command is executed.

Most of the time you would probably include this code directly in the command's command function, but it might be useful if the command in question isn't in scope of whatever is depending on it.

import { useExecuteEvent } from "cmdkit";

useExecuteEvent("myCommand", () => console.log("command was executed"));

useDoneEvent

Allows you to run additional code when a command has finished executing.

import { useDoneEvent } from "cmdkit";

useDoneEvent("myCommand", () => console.log("command is done excecuting!"));