Components Reference

registerComponents()

Register all web components. Call once at startup.

function registerComponents(): void

import { registerComponents } from 'keybinds'
registerComponents()

---

CommandPalette

Custom element: <command-palette>

Properties

Property	Type	Description
commands	Command[]	Commands to display and execute
context	object	Context for when evaluation
open	boolean	Visibility state

Attributes

Attribute	Type	Description
open	boolean	When present, palette is visible
auto-trigger	boolean	Enable $mod+K keyboard trigger
placeholder	string	Input placeholder text (default: "Type a command...")

Events

Event	Detail	Description
execute	{ command: Command }	Command was executed
close	-	Palette was dismissed

CSS Parts

Part	Element
palette	Root .palette div
backdrop	Overlay div
dialog	Main dialog container
input	Search input
list	Results ul
item	Result li
item-active	Selected result
item-disabled	Inactive result
item-label	Label span
item-description	Description span
item-category	Category span
item-key	Shortcut kbd
empty	No results message

Keyboard Navigation

Key	Action
↑ / ↓	Navigate results (wraps around)
Home / End	Jump to first / last result
Enter	Execute selected
Escape	Close palette

Keyboard and pointer input are tracked separately — moving the mouse won't hijack an in-progress keyboard selection until the pointer deliberately moves again.

---

KeybindCheatsheet

Custom element: <keybind-cheatsheet>

Properties

Property	Type	Description
commands	Command[]	Commands to display
context	object	Context for when evaluation
open	boolean	Visibility state

Attributes

Attribute	Type	Description
open	boolean	When present, cheatsheet is visible
auto-trigger	boolean	Enable hold-Control trigger (200ms)

Events

Event	Description
close	Cheatsheet was dismissed

CSS Parts

Part	Element
cheatsheet	Root div
backdrop	Overlay div
dialog	Main dialog container
group	Category group div
group-title	Category heading
list	Commands ul
item	Command li
item-disabled	Inactive command
item-label	Label span
item-keys	Keys container span
item-key	Individual kbd

---

KeybindSettings

Custom element: <keybind-settings>

Properties

Property	Type	Description
store	BindingsStore	Reactive bindings store instance
open	boolean	Visibility state

Attributes

Attribute	Type	Description
open	boolean	When present, settings panel is visible

Events

Event	Detail	Description
close	-	Settings panel was dismissed
change	{ commandId, keys?, mouse? }	A binding was changed
reset	{ commandId? }	Bindings were reset (per-command or all)

CSS Parts

Part	Element
settings	Root .settings div
backdrop	Overlay div
dialog	Main dialog container
header	Header container
title	Title text
reset-all	Reset All button
group	Category group div
group-title	Category heading
list	Commands ul
item	Command li
item-label	Label span
item-bindings	Bindings container span
item-reset	Per-command reset button
binding	Individual binding span
binding-recording	Binding in recording state
binding-keys	Key display container
binding-key	Individual kbd
binding-remove	Remove (×) button
item-add	Add binding container
add-key	Add Key button
add-mouse	Add Mouse button
recording-overlay	Recording prompt text
conflict	Conflict warning
conflict-accept	Replace button
conflict-cancel	Cancel button

Keyboard Navigation

Key	Action
Escape	Cancel recording, or close panel

---

ContextMenu

Custom element: <context-menu>

Properties

Property	Type	Description
commands	Command[]	Commands to display and execute
context	object	Context for when evaluation
menu	string	Filter to commands with matching menu tag
position	{ x: number, y: number }	Menu position in viewport coordinates
open	boolean	Visibility state

Attributes

Attribute	Type	Description
open	boolean	When present, menu is visible
auto-trigger	boolean	Listen for contextmenu on parent or target element
menu	string	Filter commands by menu tag
target	string	CSS selector for trigger element (defaults to parent)

Events

Event	Detail	Description
execute	{ command: Command }	Command was executed
close	-	Menu was dismissed

CSS Parts

Part	Element
context-menu	Root div
backdrop	Overlay div
list	Menu ul
item	Menu item li
item-active	Highlighted item
item-disabled	Inactive item
separator	Category separator
item-label	Label span
item-keys	Keys container span
item-key	Individual kbd

Keyboard Navigation

Key	Action
↑ / ↓	Navigate items (wraps around)
Home / End	Jump to first / last item
Enter	Execute selected
Escape	Close menu

Keyboard and pointer input are tracked separately — moving the mouse won't hijack an in-progress keyboard selection until the pointer deliberately moves again.

---

eventToBindingString(event)

Convert a KeyboardEvent to a canonical binding string.

function eventToBindingString(event: KeyboardEvent): string | null

Returns null for bare modifier presses and unknown keys. Uses $mod for the platform modifier (Meta on Mac, Ctrl elsewhere).

---

eventToMouseBindingString(event)

Convert a MouseEvent to a canonical binding string.

function eventToMouseBindingString(event: MouseEvent): string | null

Maps button numbers to canonical names (0=click, 1=middle, 2=right).

---

findConflict(schema, bindingStr, type, excludeId?)

Check if a binding string conflicts with any command in a schema.

function findConflict(
  schema: Schema,
  bindingStr: string,
  type: 'keys' | 'mouse',
  excludeId?: string
): { commandId: string, label: string } | null

Normalizes through parse → lookup for accurate cross-format comparison.

---

formatMouseParts(binding)

Format a mouse/scroll binding string into an array of display-ready parts.

function formatMouseParts(binding: string): string[]

formatMouseParts('$mod+click')      // ["⌘", "Click"] on Mac, ["Ctrl", "Click"] elsewhere
formatMouseParts('scrollup')        // ["Scroll ↑"]
formatMouseParts('ctrl+scrolldown') // ["Ctrl", "Scroll ↓"] on Mac, ["Ctrl", "Scroll ↓"] elsewhere

---

filterByMenu(commands, menu, context?)

Filter commands by their menu tag for context menu display.

function filterByMenu(
  commands: Command[],
  menu: string,
  context?: Record<string, unknown>
): (Command & { active: boolean })[]

Returns commands whose menu property matches (string match or array includes). Each result includes an active boolean from when evaluation. Hidden commands are excluded.

const items = filterByMenu(commands, 'editor', { hasSelection: true })

---

onModifierHold(modifiers, callback, options?)

Utility for hold-to-show behavior.

function onModifierHold(
  modifiers: string | string[],
  callback: (held: boolean) => void,
  options?: { delay?: number, target?: EventTarget }
): () => void

Parameters:

Parameter	Type	Default	Description
modifiers	string | string[]	-	Modifier key(s): 'Control', 'Alt', 'Shift', 'Meta'
callback	(held: boolean) => void	-	Called with true when held, false on release
options.delay	number	200	Hold duration in ms
options.target	EventTarget	window	Element to listen on

Returns: Cleanup function.

const cleanup = onModifierHold('Control', (held) => {
  cheatsheet.open = held
})

// Multiple modifiers (either triggers)
onModifierHold(['Control', 'Meta'], callback)

// Custom delay
onModifierHold('Alt', callback, { delay: 300 })