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
dataandsearchermust 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: 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;
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[]): voidThe console.log() static method outputs a message to the console.
log(event: CustomEvent<NinjaSelectedDetail>event.CustomEvent<NinjaSelectedDetail>.detail: NinjaSelectedDetailThe read-only detail property of the CustomEvent interface returns any data passed when initializing the event.
detail.NinjaSelectedDetail.action: INinjaAction | undefinedThe chosen action, or undefined when Enter was pressed on no match.
action?.INinjaAction.id: string | undefinedUnique 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; }.