Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More
Socket
Sign inDemoInstall
Socket

ninja-keys

Package Overview
Dependencies
Maintainers
1
Versions
22
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

ninja-keys

Ninja Keys

  • 1.1.1
  • Source
  • npm
  • Socket score

Version published
Weekly downloads
16K
decreased by-22.57%
Maintainers
1
Weekly downloads
 
Created
Source

Ninja Keys

Keyboard shortcuts interface for your website. Working with Vanilla JS, Vue, React.

FOSSA Status npm npm

Demo

Demo

Why?

A lot of applications support that pattern, user hit +k (or ctrl+k) and search UI dialog appear. I've seen recently in Notion, Slack, Linear, Vercel and Agolia, but I'm sure there are plenty more. Also, there is a Apple Spotlight, Alfred and Raycast app that using this pattern too but different shortcuts. There are already some libraries but they are too framework spesific, like larevel only or react only Althought, mine is not a silver bullet and if you need more framework integration, check them out too.

I was needed an keyboard interface for navigation for static website without any frameworks. In same time I have a few vue projects where it can be useful too. So I decided to give first shot for Web Components and Lit Element.

Why "Ninja" ?

Because it appears from nowhere and executes any actions quickly. Or because it allows your users to become keyboard ninja's 🙃

Install from NPM

npm i ninja-keys

Import if you are using webpack, rollup, vite or other build system.

import from 'ninja-keys';

Install from CDN

Mostly for usage in HTML/JS without build system.

<script type="module" src="https://unpkg.com/ninja-keys?module"></script>

or inside your module scripts

import {NinjaKeys} from 'https://unpkg.com/ninja-keys?module';

Usage

Add tag to your html.

<ninja-keys> </ninja-keys>
<script>
  const ninja = document.querySelector('ninja-keys');
  ninja.data = [
    {
      id: 'Projects',
      title: 'Open Projects',
      hotkey: 'ctrl+N',
      icon: 'apps',
      section: 'Projects',
      handler: () => {
        // it's auto register above hotkey with this handler
        alert('Your logic to handle');
      },
    },
    {
      id: 'Theme',
      title: 'Change theme...',
      icon: 'desktop_windows',
      children: ['Light Theme', 'Dark Theme', 'System Theme'],
      hotkey: 'ctrl+T',
      handler: () => {
        // open menu if closed. Because you can open directly that menu from it's hotkey
        ninja.open({ parent: 'Theme' });
        // if menu opened that prevent it from closing on select that action, no need if you don't have child actions
        return {keepOpen: true};
      },
    },
    {
      id: 'Light Theme',
      title: 'Change theme to Light',
      icon: 'light_mode',
      parent: 'Theme',
      handler: () => {
        // simple handler
        document.documentElement.classList.remove('dark');
      },
    },
    {
      id: 'Dark Theme',
      title: 'Change theme to Dark',
      icon: 'dark_mode',
      parent: 'Theme',
      handler: () => {
        // simple handler
        document.documentElement.classList.add('dark');
      },
    },
  ];
</script>

Library using flat data structure inside, as in example above. But you can also use tree structure as below:

{
  id: 'Theme',
  children: [
    { id: ':ight' title: 'light_mode', },
    { id: 'System Theme',
      children: [
        { title: 'Sub item 1' },
        { title: 'Sub item 2' }
      ]
    }
  ]
}

Attributes

FieldDefaultDescription
placeholderType a command or search...Placeholder for search
disableHotkeysfalseIf attribute exist will register all hotkey for all actions
hideBreadcrumbsfalseHide breadcrumbs on header if true
openHotkeycmd+k,ctrl+kOpen or close shortcut
navigationUpHotkeyup,shift+tabNavigation up shortcuts
navigationDownHotkeydown,tabNavigation down shortcuts
closeHotkeyescClose shotcut
goBackHotkeybackspaceGo back on one level if has parent menu
selectHotkeyenterSelect action and execute handler or open submenu
hotKeysJoinedViewfalseIf exist/true will display hotkeys inside one element
noAutoLoadMdIconsfalseIf exist it disable load material icons font on connect
Example
<ninja-keys placeholder="Must app is awesome" openHotkey="cmd+l" hideBreadcrumbs></ninja-keys>

Data

Array of INinjaAction - interface properties below

NameTypeDescription
idstringUnique id/text. Will be displayed as breadcrumb in multimenu
titlestringTitle of action
hotkeystring(optional)Shortcut to display and register
handlerFunction(optional)Function to execute on select
mdIconstring(optional)Material Design font icon name
iconstring(optional)Html to render as custom icon
parentstring(optional)If using flat structure use id of actions to make a multilevel menu
keywordsstring(optional)Keywords to use for search
childrenArray(optional)If using flat structure then ids of child menu actions. Not requried on tree structure
sectionstring(optional)Section text. Like a header will be group with other same sections

Methods

NameArgDescription
open{ parent?: string }Open menu with parent, if null them open root menu
closeClose menu
setParentparent?: stringNavigate to parent menu
Example
const ninja = document.querySelector('ninja-keys');
ninja.open() 
// or
ninja.open({ parent: 'Theme' })

Themes

Component support dark theme out-of-box. You just need to add a class.

<ninja-keys class="dark"></ninja-keys>

If you need more style control, use css variable below.

CSS variables

NameDefault
--ninja-width640px;
--ninja-backdrop-filtersaturate(180%) blur(2px);
--ninja-overflow-backgroundrgba(255, 255, 255, 0.5);
--ninja-text-colorrgb(60, 65, 73);
--ninja-font-size16px;
--ninja-top20%;
--ninja-key-border-radius0.25em
--ninja-accent-colorrgb(110, 94, 210);
--ninja-secondary-background-colorrgb(239, 241, 244);
--ninja-secondary-text-colorrgb(107, 111, 118);
--ninja-selected-backgroundrgb(248, 249, 251);
--ninja-icon-colorvar(--ninja-secondary-text-color);
--ninja-icon-size1.2em;
--ninja-separate-border1px solid var(--ninja-secondary-background-color);
--ninja-modal-background#fff;
--ninja-modal-shadowrgb(0 0 0 / 50%) 0px 16px 70px;
--ninja-actions-height300px;
--ninja-group-text-colorrgb(144, 149, 157);
--ninja-footer-backgroundrgba(242, 242, 242, 0.4);
Example
ninja-keys {
  --ninja-width: 400px;
}

Icons

By default component using icons from https://fonts.google.com/icons

For example, you can just set mdIcon to light_mode to render sun icon.

To add Material icons for website you need to add to html, for example

<link href="https://fonts.googleapis.com/css?family=Material+Icons&display=block" rel="stylesheet">

If want custom icons, you can use svg or img to insert it with icon property for action with ninja-icon class. Example:

{
  title: 'Search projects...',
  icon: `<svg xmlns="http://www.w3.org/2000/svg" class="ninja-icon" fill="none" viewBox="0 0 24 24" stroke="currentColor">
    <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M7 8h10M7 12h4m1 8l-4-4H5a2 2 0 01-2-2V6a2 2 0 012-2h14a2 2 0 012 2v8a2 2 0 01-2 2h-3l-4 4z" />
  </svg>`,
  section: 'Projects',
},

Also, you can change width and font using css variables for it

ninja-keys {
  --ninja-icon-size: 1em;
}
<ninja-keys> 
  <slot name="footer">Must custom footer or empty to hide</slot>
</ninja-keys>

Dev Server

npm run start

Linting

To lint the project run:

npm run lint

Formatting

Prettier is used for code formatting. It has been pre-configured according to the Lit's style.

License

Copyright (c) Sergei Sleptsov hey@sergei.ws

Licensed under the MIT license.

FOSSA Status

Keywords

FAQs

Package last updated on 22 Oct 2021

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc