Actions and menus

Everything in the palette is an action: a command that runs, a link, or a menu that holds more actions. The element’s data property takes them as an array of INinjaAction.

The action

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

const const action: INinjaActionaction: 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
: 'export-pdf', // unique; menus and breadcrumbs refer to it
INinjaAction.title: string

The text shown in the list, and searched.

title
: 'Export as PDF', // shown and searched
INinjaAction.section?: string

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

section
: 'File', // grouping heading
INinjaAction.keywords?: string

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

keywords
: 'print save', // searched, not shown
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
: 'ctrl+shift+e', // works with the palette closed too
INinjaAction.mdIcon?: string

A Material Icons ligature name (settings, dark_mode).

mdIcon
: 'picture_as_pdf', // a Material Icons name
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
: (self: INinjaActionself) => {
var console: Consoleconsole.Console.log(...data: any[]): void

The console.log() static method outputs a message to the console.

MDN Reference

log
(`running ${self: INinjaActionself.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
}`);
}, };

Only id and title are required. Every field is described in the API reference.

Handlers and keeping the palette open

handler runs when the action is chosen, with Enter, a click, or its hotkey, and receives the action itself. The palette closes afterwards. Return {keepOpen: true} to keep it open, for actions people repeat (zoom, next page) or ones that open a menu:

const const zoomIn: INinjaActionzoomIn: 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
: 'zoom-in',
INinjaAction.title: string

The text shown in the list, and searched.

title
: 'Zoom in',
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
.ElementCSSInlineStyle.style: CSSStyleDeclarationstyle.CSSStyleProperties.fontSize: string

The font-size CSS property sets the size of the font. Changing the font size also updates the sizes of the font size-relative units, such as em, ex, and so forth.

MDN Reference

fontSize
= '110%';
return {keepOpen?: booleankeepOpen: true}; }, };

An action with children and no handler opens its menu. One with neither fires the selected event and leaves the palette open, which is enough when the page handles selected itself (see Opening and events).

Sections

Actions with the same section are grouped under it as a heading. Sections appear in the order their first action does, so order data the way the groups should read. Actions without a section form one group with no heading, placed where the first of them is.

A menu is an action with children. Choosing it opens the menu: the list shows its children, a breadcrumb names it above the input, and Backspace on an empty search goes back up. Menus nest to any depth. They can be written two ways.

As a tree, with children holding the child actions:

const const tree: INinjaAction[]tree: 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
: 'Theme',
INinjaAction.title: string

The text shown in the list, and searched.

title
: 'Change theme…',
INinjaAction.children?: INinjaAction[] | string[]

The menu this action opens: the ids of its children in a flat list, or the child actions themselves in a tree. ninja-keys flattens a tree into ids, so a searcher always sees ids.

children
: [
{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
: 'light', INinjaAction.title: string

The text shown in the list, and searched.

title
: 'Light'},
{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
: 'dark', INinjaAction.title: string

The text shown in the list, and searched.

title
: 'Dark'},
], }, ];

Or as a flat list, where each child names its menu in parent and the menu lists the children’s ids:

const const flat: INinjaAction[]flat: 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
: 'Theme', INinjaAction.title: string

The text shown in the list, and searched.

title
: 'Change theme…', INinjaAction.children?: INinjaAction[] | string[]

The menu this action opens: the ids of its children in a flat list, or the child actions themselves in a tree. ninja-keys flattens a tree into ids, so a searcher always sees ids.

children
: ['light', 'dark']},
{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
: 'light', INinjaAction.title: string

The text shown in the list, and searched.

title
: 'Light', INinjaAction.parent?: string

The id of the menu this action is in, for a flat list.

parent
: 'Theme'},
{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
: 'dark', INinjaAction.title: string

The text shown in the list, and searched.

title
: 'Dark', INinjaAction.parent?: string

The id of the menu this action is in, for a flat list.

parent
: 'Theme'},
];

The element flattens a tree into the second form itself, so pick whichever your data already is. A flat list suits data from a server or a database; a tree suits menus written by hand. A tree’s children are given their parent from where they sit.

The breadcrumbs show the menu’s id, so give menus readable ids ('Theme', not 'menu-3').

Opening a menu directly

open({parent}) opens the palette inside a menu. A menu action’s own hotkey can do it, so the hotkey jumps straight to the choices:

const const theme: INinjaActiontheme: 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
: 'Theme',
INinjaAction.title: string

The text shown in the list, and searched.

title
: 'Change theme…',
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+t',
INinjaAction.children?: string[] | INinjaAction[]

The menu this action opens: the ids of its children in a flat list, or the child actions themselves in a tree. ninja-keys flattens a tree into ids, so a searcher always sees ids.

children
: ['light', 'dark'],
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
: () => {
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
({parent?: stringparent: 'Theme'});
return {keepOpen?: booleankeepOpen: true}; }, };

Search at the top level looks through every level, so dark finds the Dark action inside the Theme menu without opening it. Inside a menu, search looks only at that menu’s own actions (the catsearch searcher searches everything below the menu instead).

Icons

mdIcon takes a Material Icons name. The element loads that font from Google Fonts when it connects, unless the page already links it or noAutoLoadMdIcons is set.

icon takes HTML instead, usually an SVG. Give it the ninja-icon class so it is sized and coloured like the built-in icons (--ninja-icon-size, --ninja-icon-color):

const const search: INinjaActionsearch: 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
: 'search',
INinjaAction.title: string

The text shown in the list, and searched.

title
: 'Search projects…',
INinjaAction.icon?: string

HTML for a custom icon, usually an <svg>; give it the ninja-icon class to size it like the built-in ones. Rendered unescaped, so never put untrusted text in it.

icon
: `<svg class="ninja-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor"
stroke-width="2"><circle cx="11" cy="11" r="7"/><path d="m20 20-3.5-3.5"/></svg>`, };

icon is rendered as HTML, unescaped. Build it only from markup you control, never from user input. This site’s palette uses lucide icons this way.

Changing the actions

Assign a new array to data to change the actions; the element re-flattens it and rebinds every action hotkey, releasing the old ones. Mutating the array in place does not re-render it. Assigning the same array again does, which keeps frameworks that wrap data in proxies working.