hollow.keymap

June 4, 2026 · View on GitHub

Bind keys to actions or Lua callbacks. Hollow uses vim-style chord notation and supports a leader key and modal bindings (normal, copy_mode).

For the conceptual model see Keybindings. For the action list see Built-in keymap actions.

Chord syntax

FormMeaning
jSingle printable key
<C-t>Ctrl + t
<C-S-Tab>Ctrl + Shift + Tab
<A-PageDown>Alt + PageDown
<leader>rLeader key followed by r
<leader>uuLeader sequence (two us)

Mods: C- (Ctrl), S- (Shift), A- (Alt). Legacy ctrl+..., leader+..., and split mods/key APIs are not supported.

Functions

hollow.keymap.set(chord, action, opts?)         -- set or replace
hollow.keymap.del(chord, opts?)                 -- remove (returns boolean)
hollow.keymap.get(chord, opts?)                 -- read current action

hollow.keymap.set_leader(chord?, opts?)         -- set the leader key
hollow.keymap.clear_leader()                    -- remove the leader
hollow.keymap.is_leader_active()                -- boolean
hollow.keymap.get_leader_state()                -- HollowLeaderState or nil

set options:

{
  desc = "shown in the key-legend widget",
  mode = "normal",                              -- "normal" or "copy_mode"
  timeout_ms = 1200,                            -- for the leader only
}

action is either a string action name (see Built-in keymap actions) or a Lua function.

Examples

Replace a built-in action:

hollow.keymap.set("<C-t>", function()
  hollow.term.new_tab({ domain = "wsl" })
end, { desc = "new tab in wsl" })

Bind a leader sequence:

hollow.keymap.set("<leader>e", "split_vertical", { desc = "split vertical" })

Bind in copy mode:

hollow.keymap.set("h", "copy_mode_move_left", { mode = "copy_mode" })
hollow.keymap.set("gg", "copy_mode_top",     { mode = "copy_mode" })

Remove a binding:

hollow.keymap.del("<C-S-c>")

Configure the leader:

hollow.keymap.set_leader("<C-Space>", { timeout_ms = 1200 })
hollow.keymap.clear_leader()

Leader state

hollow.keymap.get_leader_state() returns a snapshot of the leader state machine when the leader is in the middle of a sequence:

HollowLeaderState = {
  active = boolean,       -- true if a sequence is in flight
  mode = HollowKeyMode,   -- current mode
  prefix = string,        -- leader key
  sequence = string[],    -- keys pressed so far
  display = string,       -- pretty version of `sequence`
  next = string[],        -- valid next keys
  next_display = string[],
  desc = string | nil,    -- description of the matching action, if any
  remaining_ms = integer, -- ms until the sequence times out
  timeout_ms = integer,
  complete = boolean,     -- sequence resolved to a final action
}

Useful for showing a leader HUD in the top bar.

A binding in normal mode only fires when copy mode is not active. Bindings in copy_mode only fire when copy mode is active. The runtime also routes on_key(key, mods) to mounted overlays before matching keymaps; see hollow.ui.overlay.

See also