Quickstart

A working palette takes the element, a list of actions, and nothing else. This page builds one; the basic example has the same thing running.

Put the element on the page

Anywhere in the body; it draws nothing until it opens, and then covers the page.

<ninja-keys placeholder="Type a command"></ninja-keys>
<script type="module" src="./main.ts"></script>

Give it actions

data takes an array of actions. Each has an id and a title; a handler runs when it is chosen.

import '@appulsauce/ninja-keys';
import type {INinjaAction} from '@appulsauce/ninja-keys';

const const actions: INinjaAction[]actions: INinjaAction[] = [
  {
    INinjaAction.id: string

Unique across all actions. Child actions name their menu by it in parent, and the breadcrumbs show it while that menu is open.

id
: 'home',
INinjaAction.title: string

The text shown in the list, and searched.

title
: 'Go home',
INinjaAction.section?: string

A heading the action is grouped under, in the order sections appear.

section
: 'Navigation',
INinjaAction.mdIcon?: string

A Material Icons ligature name (settings, dark_mode).

mdIcon
: 'home',
INinjaAction.hotkey?: string

A shortcut that runs handler from anywhere on the page, written as hotkeys-js takes it (ctrl+n, cmd+shift+p, alt+1,alt+2 for either). Shown on the action's row.

hotkey
: 'alt+h',
INinjaAction.handler?: (action: INinjaAction) => {
    keepOpen?: boolean;
} | void

Runs when the action is chosen, by Enter, a click or its hotkey. The palette closes afterwards unless it returns {keepOpen: true}.

handler
: () => {
var location: Location

The read-only location property of the Window interface returns a Location object with information about the current location of the document.

MDN Reference

location
.Location.assign(url: string | URL): void

The assign() method of the Location interface causes the window to load and display the document at the URL specified. After the navigation occurs, the user can navigate back to the page that called Location.assign() by pressing the "back" button.

MDN Reference

assign
('/');
}, }, { INinjaAction.id: string

Unique across all actions. Child actions name their menu by it in parent, and the breadcrumbs show it while that menu is open.

id
: 'theme',
INinjaAction.title: string

The text shown in the list, and searched.

title
: 'Toggle dark mode',
INinjaAction.section?: string

A heading the action is grouped under, in the order sections appear.

section
: 'Appearance',
INinjaAction.mdIcon?: string

A Material Icons ligature name (settings, dark_mode).

mdIcon
: 'dark_mode',
INinjaAction.keywords?: string

More words to match, separated by spaces; not shown.

keywords
: 'light colour scheme',
INinjaAction.handler?: (action: INinjaAction) => {
    keepOpen?: boolean;
} | void

Runs when the action is chosen, by Enter, a click or its hotkey. The palette closes afterwards unless it returns {keepOpen: true}.

handler
: () => {
var document: Document

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

MDN Reference

document
.Document.documentElement: HTMLElement

The documentElement read-only property of the Document interface returns the Element that is the root element of the document (for example, the element for HTML documents).

MDN Reference

documentElement
.Element.classList: DOMTokenList

The read-only classList property of the Element interface contains a live DOMTokenList collection representing the class attribute of the element. This can then be used to manipulate the class list.

MDN Reference

classList
.DOMTokenList.toggle(token: string, force?: boolean): boolean

The toggle() method of the DOMTokenList interface removes an existing token from the list and returns false. If the token doesn't exist it's added and the function returns true.

MDN Reference

toggle
('dark');
}, }, ]; const const ninja: NinjaKeys | nullninja = 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');
if (const ninja: NinjaKeys | nullninja) const ninja: NinjaKeysninja.NinjaKeys.data: INinjaAction[]

The actions, as a flat list (children name their menu in parent) or a tree (menus hold their children in children). Assign a new array to change it; the hotkeys are rebound each time.

data
= const actions: INinjaAction[]actions;

Open it

Press Ctrl K, or ⌘ K on a Mac, to open and close it. Typing searches titles and keywords; the arrow keys move; Enter runs the selected action; Esc closes. The hotkey of each action works with the palette closed too: Alt H goes home from anywhere on the page.

From your own button:

var document: Document

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

MDN Reference

document
.ParentNode.querySelector<Element>(selectors: string): Element | null (+4 overloads)

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

MDN Reference

querySelector
('#search-button')?.Element.addEventListener<K>(type: K, listener: (this: Element, ev: ElementEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void (+1 overload)

The addEventListener() method of the EventTarget interface sets up a function that will be called whenever the specified event is delivered to the target.

MDN Reference

addEventListener
('click', () => {
const ninja: NinjaKeysninja.
NinjaKeys.open(options?: {
    parent?: string;
    search?: string;
} | undefined): void

Show a modal.

search starts the search box with that text, as if typed: a host that opens the palette on a key press can pass on what the user typed while it was opening, instead of dropping it or letting it reach the page.

open
();
});

Where next