rune.bind

Key bindings run named input actions or Lua callbacks on key presses. For a task-oriented introduction, see Keybindings.

Quick reference

rune.bind(key, action, opts?)   -- bind a key; rebinding replaces (upsert by key)
rune.unbind(key)                  -- remove a binding; true if one existed
rune.binds.get(key)               -- the binding's handle, or nil

rune.bind returns a handle and accepts the common option group. The key is the bind’s name, so a name in opts is ignored with a notice. When a bind would otherwise run, disabling it (or its group) consumes the key without calling the callback.

rune.bind("f1", function() rune.send("north") end, {group = "combat"})

The input action table lists the named actions: input.submit, input.newline, input.toggle_mode, input.open_editor, input.cancel, input.delete_word, input.word_left, and input.word_right, including their defaults and context rules. Unknown action strings are errors. Action names are not commands to send.

local handles = rune.bind({"shift+enter", "ctrl+j"}, "input.newline")
handles[1]:remove() -- removes Shift+Enter only
rune.bind("ctrl+s", "input.submit") -- adds another submit key
rune.unbind("enter") -- removes the default submit key

A key array is shorthand for separate registrations and returns an array of handles. The entire key array and options type are checked before registration. A single key still returns one handle. Existing callback bindings are unchanged. :action() returns the registered function or action string; only functions can be called directly. Hints use the earliest registered active alias for each input action and disappear when none remain.

To extend a default rather than discard it, capture its action first:

local scroll = assert(rune.binds.get("pgup")):action()
rune.bind("pgup", function()
    scroll()
    rune.echo("scrolled")
end)

Key format

key is a Rune key name such as "j", "ctrl+r", "pgup", or "f13". The key-name table, modifier order, terminal caveats, and reserved keys are documented under Key names. Aliases are not normalized: use esc, pgup, and pgdown, not escape, pageup, or pagedown.

Dispatch behavior and defaults

The Keybindings guide describes where binds run and the default keymap. It distinguishes normal input, inline and modal pickers, scrollback search, and the draft editor.

Managing

Standard registry management applies, addressed by key: rune.binds.get/enable/disable/remove(key), .list(), .count(), .clear(), .remove_group(group). See Registries. /binds lists everything.

Related: Keybindings guide · rune.input · rune.ui.picker · rune.pane