Frameworks

<ninja-keys> is a standard custom element, so it works anywhere an element does. Two things differ between frameworks: how a value reaches a property rather than an attribute, and where the import runs when pages render on a server.

What to pass as what

  • data and searcher must be properties: an array of actions with functions in it, and a function, cannot be attributes.
  • Everything else (placeholder, openHotkey, hideBreadcrumbs, …) works either way. As attributes, names are lowercase: openhotkey, hidebreadcrumbs.
  • The element fires plain DOM events (selected, change, open, close), not framework events; listen with whatever the framework uses for DOM events.

Plain HTML and TypeScript

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;
const ninja: NinjaKeysninja.NinjaKeys.addEventListener<"selected">(type: "selected", listener: (this: NinjaKeys, event: CustomEvent<NinjaSelectedDetail>) => unknown, options?: boolean | AddEventListenerOptions): void (+2 overloads)addEventListener('selected', (event: CustomEvent<NinjaSelectedDetail>event) => { var console: Consoleconsole.Console.log(...data: any[]): void

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

MDN Reference

log
(event: CustomEvent<NinjaSelectedDetail>event.CustomEvent<NinjaSelectedDetail>.detail: NinjaSelectedDetail

The read-only detail property of the CustomEvent interface returns any data passed when initializing the event.

MDN Reference

detail
.NinjaSelectedDetail.action: INinjaAction | undefined

The chosen action, or undefined when Enter was pressed on no match.

action
?.INinjaAction.id: string | undefined

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

id
);
}); }

React

React 19 sets properties on custom elements when the element has them, so data can be passed as a prop. Import the element in an effect if the component also renders on a server.

import {useEffect, useRef} from 'react';
import type {INinjaAction, NinjaKeys, NinjaSelectedDetail} from '@appulsauce/ninja-keys';

export function CommandPalette({actions}: {actions: INinjaAction[]}) {
  const ref = useRef<NinjaKeys>(null);

  useEffect(() => {
    void import('@appulsauce/ninja-keys');
    const ninja = ref.current;
    const onSelected = (event: CustomEvent<NinjaSelectedDetail>) =>
      console.log(event.detail.action?.id);
    ninja?.addEventListener('selected', onSelected);
    return () => ninja?.removeEventListener('selected', onSelected);
  }, []);

  return <ninja-keys ref={ref} data={actions} placeholder="Search" />;
}

In TypeScript, declare the tag for JSX once:

import type {NinjaKeys} from '@appulsauce/ninja-keys';
import type {DetailedHTMLProps, HTMLAttributes} from 'react';

declare module 'react' {
  namespace JSX {
    interface IntrinsicElements {
      'ninja-keys': DetailedHTMLProps<HTMLAttributes<NinjaKeys>, NinjaKeys> &
        Partial<
          Pick<
            NinjaKeys,
            'data' | 'placeholder' | 'openHotkey' | 'hideBreadcrumbs'
          >
        >;
    }
  }
}

With React 18 and earlier, set data through the ref (ref.current.data = actions) instead: they pass everything to custom elements as attributes.

Vue

Tell the compiler the tag is a custom element, then bind data as a property with .prop:

// vite.config.ts
vue({
  template: {compilerOptions: {isCustomElement: (tag) => tag === 'ninja-keys'}},
});
<script setup lang="ts">
import '@appulsauce/ninja-keys';
import type {INinjaAction, NinjaSelectedDetail} from '@appulsauce/ninja-keys';

const actions: INinjaAction[] = [{id: 'home', title: 'Go home'}];
const onSelected = (event: CustomEvent<NinjaSelectedDetail>) =>
  console.log(event.detail.action?.id);
</script>

<template>
  <ninja-keys
    :data.prop="actions"
    placeholder="Search"
    @selected="onSelected"
  />
</template>

The element re-renders every time data is assigned, even with the same array, so Vue’s reactive proxies around the array do not hide changes from it.

Svelte

Svelte sets a property when the element has it, so plain attributes work once the element is defined. Import it in the browser only if the page is server-rendered:

<script lang="ts">
  import type {INinjaAction, NinjaKeys} from '@appulsauce/ninja-keys';
  import {onMount} from 'svelte';

  let {actions}: {actions: INinjaAction[]} = $props();
  let ninja: NinjaKeys | undefined = $state();

  onMount(() => {
    void import('@appulsauce/ninja-keys');
  });

  $effect(() => {
    if (ninja) ninja.data = actions;
  });
</script>

<ninja-keys bind:this={ninja} placeholder="Search"></ninja-keys>

This site is SvelteKit, and its search palette is built this way: src/lib/components/SearchPalette.svelte in the repository.

Server rendering

The element touches HTMLElement and document when it is defined, which do not exist on a server. Render the tag as part of the page (it is empty until defined), and load the module in the browser: in an effect, onMount, or a client-only component. Until the module loads, a page can hide slotted content with ninja-keys:not(:defined) { display: none; }.