kmenu v2.0.0

Consulting

If you're a startup or founder using this for your application and need some help setting it up, or perhaps even need a separate cmdk interface tailored to your application, you can reach out to at hi.harsh@pm.me.

Quickstart

View the official documentation for more thorough examples and documentation.

Having trouble? Unsure of something? Feel free to ask away in the discussions.

Install the npm package:

npm add kmenu
yarn add kmenu
pnpm add kmenu

Using the Provider

After you install, you must wrap your application around the MenuProvider component. If your application has some values (padding/margin/etc) which override the styles of the menu, you need to explicitly define the height of each command component and each section in your code. Here's a look:

Now, here's a look at the dimensions object:

Here's how you'd use your menu provider:

import { MenuProvider, Dimensions } from 'kmenu'

export default ({ children }) => {
  const dimensions: Dimensions = {}

  return <MenuProvider dimensions={dimensions}>{children}</MenuProvider>
}

Commands

The commands are broken up into two arrays: an array that contains the different categories of the commands, and another array contains the commands itself. Here's how you can define categories:

Here's how you create commands:

We can create our commands array like this:

import type { Command } from 'kmenu'

const main: Command[] = [
  {
    category: 'Utility',
    commands: [
      {
        icon: <Dashboard />,
        text: 'Dashboard',
        href: '/dashboard',
        keywords: ['home', 'back'],
      },
      {
        icon: <Cloud />,
        text: 'Deployments',
        href: '/deployments',
      },
      {
        icon: <ArrowLeft />,
        text: 'Previous',
        perform: () => navigateToPreviousPage(),
        keywords: ['back']
      },
    ],
    subCommands: [
      {
        icon: <ExternalLink />,
        text: 'Home',
        href: '/',
        newTab: true,
      },
    ],
  },
]

Shortcuts

Each shortcut can have two target keys and a modifier:

Command Wrapper

Be sure to wrap ALL your menus around a CommandWrapper component. This component contains things like the breadcrumbs and the search bar. You can pass in a default value for the input on the command wrapper:

Command Menu

Here are all the options available on the menu:

The index is the index of this menu—if you only have a single menu, set this to one. This number is used for opening and closing multiple menus, whenever you want to open a sub menu simply use the setOpen command and input the index of the menu you'd like to open. For more information on this, see nested menus.

useCommands

After you define your components, you must input them into the useCommands hook. Learn more about it here.

export default () => {
  const main = [
    /* ... */
  ];
  const [mainCommands] = useCommands(main);

  return (
    <CommandWrapper>
      <CommandMenu commands={mainCommands} index={1} crumbs={['Home']} />
    </CommandWrapper>
  );
};

That's about all the configuration you'll need to do in order to get a basic command menu to work.

The possibilities are with these menus infinite: you can add custom loading states, sub-commands, and so much more. For a full list, check out the examples.

useKmenu Hook

useKmenu is a utility hook that adds utility and gives you information about the current status of the menu. You can use these for a multitude of different things such as nested routes on the command menu or for toggling the menu through a button on your UI.

Here's a list of all the information it provides:

Here's an example of how you can toggle the menu open with the click of a button:

import { useKmenu } from 'kmenu'

export default () => {
  const { toggle } = useKmenu()
  return <button onClick={toggle}>Toggle Menu</button>
}

REMINDER: YOUR APPLICATION OR PARENT COMPONENT MUST BE WRAPPED IN THE MENUPROVIDER

Examples

In an attempt to showcase everything this menu can do, examples/src/kmenu includes an ever-growing list some things you can do with kmenu:

• Basic
• Nested menus
• Checkboxes
• Loading states
• Modal

This list is ever-growing. If there's something you ever want to add, any and all pull requests are always welcomed.