Keyboard

Basic key handling

Keyboard events include the key name and modifier flags (ctrl, alt, shift). You can listen globally on the renderer to implement application shortcuts.

renderer.on("key", (event) => {
  console.log("Key:", event.name)
  console.log("Ctrl:", event.ctrl)
  console.log("Alt:", event.alt)
  console.log("Shift:", event.shift)
})

Use this approach for app-wide shortcuts like quit, help, toggles, and navigation between screens.

Common patterns

Common patterns include quitting on Ctrl+C, showing help on ?, opening a debug overlay on Ctrl+D, and switching focus with Tab.

renderer.on("key", (event) => {
  if (event.ctrl && event.name === "c") renderer.destroy()
  if (event.name === "?") renderer.console.toggle()
})

For component-level keyboard interactions, attach onKey handlers to interactive components (inputs, lists, editors) so the behaviour is scoped to focus.

<input
  placeholder="Search"
  onKey={(event) => {
    if (event.name === "enter") submit()
    if (event.name === "escape") cancel()
  }}
/>

Paste events

Pasted text should be handled separately from per-key input. If you implement your own editor, treat paste as an atomic insertion into the buffer.

renderer.on("paste", (event) => {
  console.log("Pasted:", event.text)
})

Focus and key routing

Focus matters: global handlers are useful for app-wide shortcuts, but per-component handlers make it easier to build isolated widgets. A typical pattern is to handle “quit” globally, but leave editing/navigation to the focused component.

When building multi-panel apps, implement a small focus manager. Keep an ordered list of focusable ids and move focus on Tab / Shift+Tab. This keeps navigation predictable even as panels mount and unmount.