Installation

ninja-keys is one custom element, <ninja-keys>, built with Lit. It has two runtime dependencies, lit and hotkeys-js, and works in any page or framework that can put an element in the DOM.

pnpm add @appulsauce/ninja-keys    # or: npm install @appulsauce/ninja-keys

Import it

Importing the package defines the element, once, for the whole page:

import '@appulsauce/ninja-keys';

The same module exports the element’s class and every type, for TypeScript:

import type {INinjaAction, class NinjaKeys

A keyboard command palette: a modal list of actions, opened with a hotkey, searched as you type, with nested menus and per-action hotkeys.

@fireschange - On every change of the search text. detail is {search: string, actions: INinjaAction[]}, the actions now shown.@firesselected - When an action is chosen, or Enter is pressed with nothing to choose. detail is {search: string, action?: INinjaAction}.@firesopen - When the palette becomes visible, however it was opened.@firesclose - When the palette is hidden, however it was closed: a method, a hotkey, Escape, a click on the overlay, or an action.@slotfooter - Replaces the key-hint footer; an empty element hides it.@csspartactions-list - The scrolling list that holds every action.@csspartninja-action - One action row.@csspartninja-selected - The selected action row.@csspartninja-icon - An action's Material icon.@csspartninja-input - The search input.@csspartninja-input-wrapper - The element around the search input.@csspartninja-search-hint - The line under the input holding a searcher's completions and notice.@csspartninja-suggestion - One completion chip.@csspartninja-notice - A searcher's notice.@cssprop[--ninja-width=640px] - Width of the palette.@cssprop[--ninja-top=20%] - Distance from the top of the viewport.@cssprop[--ninja-font-size=16px] - Base size every other size scales from.@cssprop[--ninja-font-family=inherit] - Font of the palette.@cssprop[--ninja-code-font-family=ui-monospace, monospace] - Font of completion chips.@cssprop[--ninja-z-index=1] - Stacking order of the overlay.@cssprop[--ninja-backdrop-filter=none] - Filter behind the overlay, such as blur(4px).@cssprop[--ninja-overflow-background=rgba(255, 255, 255, 0.5)] - The overlay over the page.@cssprop[--ninja-modal-background=#fff] - Background of the palette.@cssprop[--ninja-modal-shadow=rgb(0 0 0 / 50%) 0px 16px 70px] - Shadow of the palette.@cssprop[--ninja-text-color=rgb(60, 65, 73)] - Text.@cssprop[--ninja-accent-color=rgb(110, 94, 210)] - Caret, selection bar and focused chips.@cssprop[--ninja-secondary-text-color=rgb(107, 111, 118)] - Hints, keys and breadcrumbs.@cssprop[--ninja-secondary-background-color=rgb(239, 241, 244)] - Key badges, breadcrumbs and chips.@cssprop[--ninja-selected-background=rgb(248, 249, 251)] - The selected row.@cssprop[--ninja-selected-text-color=inherit] - Text of the selected row.@cssprop[--ninja-placeholder-color=#8e8e8e] - Placeholder of the input.@cssprop[--ninja-group-text-color=rgb(144, 149, 157)] - Section headers.@cssprop[--ninja-icon-color=var(--ninja-secondary-text-color)] - Icons.@cssprop[--ninja-icon-size=1.2em] - Icons.@cssprop[--ninja-key-border-radius=0.25em] - Key badges, breadcrumbs and chips.@cssprop[--ninja-separate-border=1px solid var(--ninja-secondary-background-color)] - Lines between the input, the list and the footer.@cssprop[--ninja-actions-height=300px] - Maximum height of the list.@cssprop[--ninja-footer-background=rgba(242, 242, 242, 0.4)] - The footer.
NinjaKeys
, type Searcher = (search: string, actions: readonly INinjaAction[], context: SearchContext) => SearchResult

Decides which actions a search shows. ninja-keys calls it on every render with the flattened action list, so it should be cheap; cache anything derived from actions by the array's identity, which only changes when data is set.

Searcher
} from '@appulsauce/ninja-keys';
const
const ninja: NinjaKeys | null
ninja
= var document: Document

window.document returns a reference to the document contained in the window.

MDN Reference

document
.ParentNode.querySelector<"ninja-keys">(selectors: "ninja-keys"): NinjaKeys | null (+4 overloads)

Returns the first element that is a descendant of node that matches selectors.

MDN Reference

querySelector
('ninja-keys');

document.querySelector('ninja-keys') is typed as NinjaKeys | null without a cast: the package declares the tag in HTMLElementTagNameMap.

Without a build step

The package is ES modules, so a page with no bundler can load it from a CDN that resolves bare imports, such as esm.sh or unpkg’s ?module:

<script type="module" src="https://esm.sh/@appulsauce/ninja-keys@1.3.0"></script>
<ninja-keys></ninja-keys>

Pin a version in the URL, as here, for anything you ship.

catsearch, for field queries

The field query searcher lives at @appulsauce/ninja-keys/catsearch and is built on the catsearch package. catsearch is an optional peer dependency: install it next to @appulsauce/ninja-keys only if you use that searcher. The main entry never loads it.

pnpm add catsearch    # or: npm install catsearch

Unreleased changes

To try what is on main before a release, build the repository and install the folder:

git clone https://github.com/KaiErikNiermann/ninja-keys.git
cd ninja-keys && pnpm install && pnpm run build
cd ../your-project && pnpm add ../ninja-keys

Icons

Actions can show a Material Icons glyph by name (mdIcon). For that, the element adds the Material Icons stylesheet from Google Fonts to the page when it connects, unless the page already has one. Set noAutoLoadMdIcons to stop it, for example when you use your own SVG icons or must not load third-party fonts. See Actions and menus.