2.0.0 • Published 1 year ago

kmenu v2.0.0

Weekly downloads
-
License
MIT
Repository
github
Last release
1 year ago

image

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:

ParameterDescriptionTypeOptional
dimensionsHeight values of different elements in the menu (px)Dimensions

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

ParameterDescriptionTypeDefaultOptional
commandHeightThe height of each command in the palette (px)number54
sectionHeightThe height of each category/section in the palette (px)number31
commandsThe maximum number of commands displayed on menu without overflownumber5

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:

ParameterDescriptionTypeOptional
categoryThe name of the category the command will be displayed instring
commandsAn array of commands passed onto the categoryCommand
subCommandsAn array of commands passed onto the category only accessible by searchCommand

Here's how you create commands:

ParameterDescriptionTypeOptional
iconThe icon displayed next to the commandReactElement
textThe text displayed on the commandstring
performThe action to performvoid
hrefThe link to openvoid
newTabWhether or not the link should open in a new tabboolean
keywordsSearch keywords for the commandstring
shorcutsThe keyboard shortcuts displayed on the commandShortcut
closeOnCompleteWhether the menu should close after command executesboolean
anchorAllow for custom HTML to be passed as the anchor propertyNavLink
checkboxAdd a checkbox to the commandCheckbox

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:

ParameterDescriptionTypeOptional
keysThe key(s) that the shortcut is listening forstring, string? (must be valid)
modifierThe modifier key which can will activate the shortcutstring (must be valid) or ReactElement

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:

ParameterDescriptionTypeOptional
defaultValueThe default value on the inputstring

Command Menu

Here are all the options available on the menu:

ParameterDescriptionTypeOptional
commandsThe commands for this menu to displayCommand[]
indexThe index of this menunumber
crumbsThe current path of the command menustring[]
preventSearchDisable filtering results for the menustring
loadingPlaceholderElement to be displayed while commands loadReactElement
loadingStateWhether or not the data is currently loadingboolean
placeholderThe placeholder text on this particular menustring

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:

ParameterDescriptionType
inputThe current text in the search bar of the menu that is currently openstring
setInputThe setter function to change the inputDispatch\<SetStateAction\>
isOpenWhether or not the menu is currently openboolean
openThe index of the menu is currently opennumber
setOpenThe setter function to change the open state(index: number, preventAnimate?: boolean) => void
toggleThe function for toggling the main menu open/closevoid

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:

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

2.0.0-beta

1 year ago

2.0.0

1 year ago

2.0.0-1-dev

1 year ago

2.0.0-dev

1 year ago

1.4.3

2 years ago

1.4.2

2 years ago

1.4.11-beta

2 years ago

1.4.1-beta

2 years ago

1.3.1-beta

2 years ago

1.4.31

2 years ago

1.4.32

2 years ago

1.4.0-beta

2 years ago

1.3.0-beta

2 years ago

1.2.2-dev

2 years ago

1.2.2-nightly

2 years ago

1.2.0-dev

3 years ago

1.2.0-nightly

3 years ago

1.2.1-dev

3 years ago

1.1.0-beta

3 years ago

1.0.6-beta

3 years ago

1.0.8-beta

3 years ago

1.0.7-beta

3 years ago

1.0.9-beta

3 years ago

1.0.5-beta

3 years ago

1.0.4-beta

3 years ago

1.0.3-beta

3 years ago

1.0.2-beta

3 years ago

1.0.1-beta

3 years ago

1.0.0-beta-git

3 years ago

1.0.0-beta-dev

3 years ago

1.0.0-beta

3 years ago

1.0.0-git

3 years ago

1.0.0-dev

3 years ago

1.0.0-dev-git

3 years ago

0.0.25-dev

3 years ago

0.0.25-beta

3 years ago

0.0.25

3 years ago

0.0.24

3 years ago

0.0.23-beta

3 years ago

0.0.22

3 years ago

0.0.21

3 years ago

0.0.2-dev

3 years ago

0.0.2

3 years ago