Basic palette

Six actions in three sections, each with a Material icon; three have hotkeys. Open the palette and try:

  • typing re: the Files section narrows to Open recent, matched on its keywords too (reopen);
  • pressing Enter on Zoom in: the palette stays open, because its handler returns {keepOpen: true};
  • closing the palette and pressing Alt N: an action’s hotkey works without the palette.
Handlers and events report here.
basic.ts
// A flat list of actions in three sections, with Material icons, hotkeys
// and handlers. `setup` gets this demo's <ninja-keys> and a `report`
// function that writes to the line above; on your page the element is
// `document.querySelector('ninja-keys')`.
import '@appulsauce/ninja-keys';
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
} from '@appulsauce/ninja-keys';
export default function function setup(ninja: NinjaKeys, report: (message: string) => void): voidsetup( ninja: NinjaKeysninja: 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
,
report: (message: string) => voidreport: (message: stringmessage: string) => void ): void { 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
: 'new-file',
INinjaAction.title: string

The text shown in the list, and searched.

title
: 'New file',
INinjaAction.section?: string

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

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

A Material Icons ligature name (settings, dark_mode).

mdIcon
: 'note_add',
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+n',
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
: () => report: (message: string) => voidreport('New file'),
}, { 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
: 'open-recent',
INinjaAction.title: string

The text shown in the list, and searched.

title
: 'Open recent…',
INinjaAction.section?: string

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

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

A Material Icons ligature name (settings, dark_mode).

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

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

keywords
: 'previous last reopen',
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
: () => report: (message: string) => voidreport('Open recent'),
}, { 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
: 'share',
INinjaAction.title: string

The text shown in the list, and searched.

title
: 'Share link',
INinjaAction.section?: string

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

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

A Material Icons ligature name (settings, dark_mode).

mdIcon
: 'link',
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+s',
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
: (action: INinjaActionaction) => report: (message: string) => voidreport(`${action: INinjaActionaction.INinjaAction.title: string

The text shown in the list, and searched.

title
}: copied`),
}, { 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
: 'zoom-in',
INinjaAction.title: string

The text shown in the list, and searched.

title
: 'Zoom in',
INinjaAction.section?: string

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

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

A Material Icons ligature name (settings, dark_mode).

mdIcon
: 'zoom_in',
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+=',
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
: () => {
report: (message: string) => voidreport('Zoom in (the palette stays open)'); // Keep the palette open for actions people repeat. return {keepOpen?: booleankeepOpen: true}; }, }, { 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
: 'full-screen',
INinjaAction.title: string

The text shown in the list, and searched.

title
: 'Toggle full screen',
INinjaAction.section?: string

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

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

A Material Icons ligature name (settings, dark_mode).

mdIcon
: 'fullscreen',
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
: () => report: (message: string) => voidreport('Full screen'),
}, { 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
: 'docs',
INinjaAction.title: string

The text shown in the list, and searched.

title
: 'Read the docs',
INinjaAction.section?: string

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

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

A Material Icons ligature name (settings, dark_mode).

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

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

keywords
: 'manual guide',
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
: () => report: (message: string) => voidreport('Docs'),
}, ]; 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;
}

This is the whole of the Quickstart. The fields are described in Actions and menus.