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: stringUnique 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: stringThe text shown in the list, and searched.
title: 'Go home',
INinjaAction.section?: stringA heading the action is grouped under, in the order sections appear.
section: 'Navigation',
INinjaAction.mdIcon?: stringA Material Icons ligature name (settings, dark_mode).
mdIcon: 'home',
INinjaAction.hotkey?: stringA 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: LocationThe read-only location property of the Window interface returns a Location object with information about the current location of the document.
location.Location.assign(url: string | URL): voidThe 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.
assign('/');
},
},
{
INinjaAction.id: stringUnique 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: stringThe text shown in the list, and searched.
title: 'Toggle dark mode',
INinjaAction.section?: stringA heading the action is grouped under, in the order sections appear.
section: 'Appearance',
INinjaAction.mdIcon?: stringA Material Icons ligature name (settings, dark_mode).
mdIcon: 'dark_mode',
INinjaAction.keywords?: stringMore 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: Documentwindow.document returns a reference to the document contained in the window.
document.Document.documentElement: HTMLElementThe 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).
documentElement.Element.classList: DOMTokenListThe 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.
classList.DOMTokenList.toggle(token: string, force?: boolean): booleanThe 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.
toggle('dark');
},
},
];
const const ninja: NinjaKeys | nullninja = var document: Documentwindow.document returns a reference to the document contained in the window.
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.
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: Documentwindow.document returns a reference to the document contained in the window.
document.ParentNode.querySelector<Element>(selectors: string): Element | null (+4 overloads)Returns the first element that is a descendant of node that matches selectors.
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.
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
- Actions and menus: nested menus, sections, icons.
- Hotkeys: the palette’s own keys and how to change them.
- Search: replace how the palette searches, or use field queries.
- Styling: dark mode, CSS properties and shadow parts.
- Frameworks: React, Vue and Svelte.