05_WhichKey.md

🛟 WhichKey

The WhichKey HUD shows the available bindings for the current submap, including their descriptions.

HyprVim.WhichKey.mp4

It works for HyprVim submaps and your own submaps too.

⚙️ Configuration

Requirements

Tool	Description
eww	Renders the HUD overlay
socat	Listens for Hyprland submap changes

Setup

Enable WhichKey from your Lua config:

require("lua/plugins/hyprvim").setup({
  which_key = {
    enabled = true,
    delay_ms = 0,
    vim_delay_ms = 300,
    position = "bottom-right",
    auto_show = {
      disabled = { "NORMAL", "VISUAL", "V-LINE", "INSERT" },
      enabled = nil,
    },
  },
})

The important knobs are:

• enabled turns the HUD on or off
• delay_ms controls the normal submap delay
• vim_delay_ms gives operator-pending submaps a different delay
• position anchors the HUD
• auto_show.disabled suppresses specific submaps
• auto_show.enabled whitelists only the listed submaps

Usage

The HUD auto-shows when you enter a submap and hides when you leave it. Press SPACE to toggle it manually from any mode.

HyprVim also binds leader + SHIFT + SLASH to toggle WhichKey when the feature is enabled.

Only bindings with a description appear in the HUD. For your own binds in keymaps, set a desc in the bind options:

require("lua/plugins/hyprvim").setup({
  keymaps = {
    NORMAL = {
      { "H", function() my_left() end, { desc = "Move left" } },
      { "J", function() my_down() end, { desc = "Move down" } },
      { "SUPER + X", function() my_extra() end, { desc = "Extra action" } },
    },
  },
})

Descriptions that start with + render in a distinct accent color. HyprVim uses this for submap transition rows.

Overflow Handling

If the HUD would exceed the available screen height, it automatically switches to a multi-column centered layout.

That layout still has a vertical limit, so keep custom descriptions concise when possible.

🎨 Styling

WhichKey styling still uses its own theme files. HyprVim reads them from ~/.config/hyprvim/.

On first run, HyprVim creates:

• ~/.config/hyprvim/theme.conf
• ~/.config/hyprvim/whichkey.scss

Edit theme.conf for colors and base sizing:

# ~/.config/hyprvim/theme.conf

$bg_core: #070C13;
$bg_border: #5D8BBB;
$fg: #F7EDE1;
$primary: #7FA3C9;
$secondary: #D6CE7C;
$accent: #FFA0A0;
$info: #B0C8DE;

$base_font_size = 12px

Edit whichkey.scss for layout and spacing overrides:

// ~/.config/hyprvim/whichkey.scss

.wk {
  border-radius: 16px;
}

.wk {
  padding: 6px 10px;
}

.wk-key {
  color: $accent;
}

Changes are picked up on the next hyprctl reload.

☎️ Calling It Yourself

You can also trigger the HUD from your own Hyprland binds if you need custom integration. The internal entrypoints live under scripts/ and whichkey/render.lua.

For normal use, the built-in SPACE toggle and automatic submap display are enough.

Otherwise you may call it manually like so:

hl.bind("SHIFT + SLASH", function() require("lua.plugins.hyprvim").whichkey.toggle() end, { desc = "Open WhichKey" } )

>> Next: Go to Tips and Tricks