How to Configure Hyprland Keybindings: A Complete Guide to the binds Section

Hyprland keybindings are defined in ~/.config/hypr/hyprland.conf using the bind keyword, parsed by CKeybindManager, and stored as SKeybind objects that map modifier+key combinations to actions like exec, kill, or switchworkspace.

Hyprland is a dynamic tiling Wayland compositor that reads user keybindings from a central configuration file. All keyboard shortcuts are processed by the CKeybindManager class (implemented in src/managers/KeybindManager.cpp) and stored internally as SKeybind structures defined in src/config/Keybind.hpp. Understanding how to configure Hyprland keybindings allows you to customize window management, application launching, and workspace navigation to match your workflow.

Understanding the Hyprland Keybinding Syntax

The configuration parser reads bind entries from the binds section of your config. According to the source code in src/managers/KeybindManager.hpp, each binding follows this strict syntax:

bind = <MODIFIER>, <KEY>, <ACTION>, <ARG>, <OPTIONS...>

The CKeybindManager creates a SKeybind object for each entry, populating fields that correspond directly to the Lua-exposed LuaKeybind object shown in the test suite at tests/config/lua/LuaObjectsBasic.cpp.

Modifiers and Keys

The <MODIFIER> field accepts one or more of: SUPER, ALT, CTRL, SHIFT, or META. Combine multiple modifiers with spaces (e.g., SUPER SHIFT).

The <KEY> field accepts the key symbol name, such as Q, RETURN, SPACE, UP, or F1. These map to the keycode member of the internal SKeybind structure.

Actions and Arguments

The <ACTION> field determines what Hyprland executes when the binding activates. Common actions include:

• exec – Run a shell command (requires command as <ARG>)
• kill – Close the focused window
• togglefloating – Switch the focused window between tiled and floating
• switchworkspace – Jump to a workspace (requires workspace number as <ARG>)
• movefocus – Change focus in a direction (requires direction l, r, u, d as <ARG>)

The <ARG> parameter is optional and depends entirely on the chosen action. For example, exec requires the command string, while kill requires no argument.

Advanced Keybinding Options

Hyprland supports optional flags in the <OPTIONS...> segment that modify how the binding behaves. These map to boolean flags in the SKeybind structure:

• repeat – Allow the key to repeat while held (fires continuously)
• release – Fire the action on key-release instead of key-press
• nonconsuming – Let the key event propagate to the client after the action executes
• locked – Keep the binding active even when the compositor is locked
• ignoremods – Ignore modifier state when matching the key

# Move focus left with Super+H, allowing repeat while held

bind = SUPER, H, movefocus, l, repeat

# Open a notification on key release (Super+N)

bind = SUPER, N, exec, notify-send "Hello", release

Organizing Bindings with Sub-maps

Keybindings can be grouped into sub-maps (named collections) to create modal keybinding schemes. The current sub-map is stored in SKeybind::submap.name as shown in the Lua test metadata handling.

Use the submap keyword to define and switch contexts:

# Switch to custom sub-map

submap = mymap

# Bindings only active in mymap

bind = SUPER, X, exec, xclock
bind = SUPER, Y, exec, xeyes

# Return to the default map

submap = default

This architecture allows you to create dedicated modes for window resizing, application launching, or media control without conflicting with your primary bindings.

Device-Specific and Long-Press Bindings

The SKeybind structure supports additional advanced features exposed through configuration options:

• Device-specific bindings – Restrict a binding to particular input devices using the device option (e.g., device = kbd-0)
• Long-press – Trigger an action only after the key is held for a configurable duration using the longpress flag
• Drag/Click – Treat the binding as a mouse drag or click using drag or click flags

These options allow granular control over input handling, particularly useful for laptops with multiple keyboard layouts or external input devices.

Summary

• Hyprland reads keybindings from ~/.config/hypr/hyprland.conf in a binds section
• The syntax follows bind = MODIFIER, KEY, ACTION, ARG, OPTIONS as parsed by CKeybindManager
• Internal representation uses SKeybind objects defined in src/config/Keybind.hpp
• Available actions include exec, kill, togglefloating, switchworkspace, and movefocus
• Options like repeat, release, locked, and nonconsuming modify binding behavior
• Sub-maps allow modal keybinding contexts via the submap keyword

Frequently Asked Questions

Where is the Hyprland keybinding configuration file located?

By default, Hyprland reads keybindings from ~/.config/hypr/hyprland.conf. The CKeybindManager parses this file at startup, creating SKeybind objects for each bind entry it encounters in the binds section.

How do I make a keybinding trigger on key release instead of press?

Append the release option to your bind line: bind = SUPER, N, exec, notify-send "Hello", release. This sets the corresponding flag in the SKeybind structure that CKeybindManager checks during event processing.

What are sub-maps in Hyprland and how do I use them?

Sub-maps are named collections of keybindings that create modal contexts. Define them using submap = name, add bindings underneath, then return to defaults with submap = default. Internally, Hyprland tracks the active sub-map in SKeybind::submap.name and only activates bindings matching the current context.

Can I make a keybinding that repeats while the key is held?

Yes, add the repeat flag to the binding options: bind = SUPER, H, movefocus, l, repeat. This allows the action to fire continuously while the key remains pressed, handled by the repeat logic in src/managers/KeybindManager.cpp.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}