# How to Configure Hyprland Keybindings: A Complete Guide to the binds Section > Master Hyprland keybindings by configuring the binds section in hyprland.conf. Learn to map key combinations to actions for efficient workflow control. - Repository: [Hypr Development/Hyprland](https://github.com/hyprwm/Hyprland) - Tags: how-to-guide - Published: 2026-07-29 --- **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`](https://github.com/hyprwm/Hyprland/blob/main/src/managers/KeybindManager.cpp)) and stored internally as `SKeybind` structures defined in [`src/config/Keybind.hpp`](https://github.com/hyprwm/Hyprland/blob/main/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`](https://github.com/hyprwm/Hyprland/blob/main/src/managers/KeybindManager.hpp), each binding follows this strict syntax: ```conf bind = , , , , ``` 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`](https://github.com/hyprwm/Hyprland/blob/main/tests/config/lua/LuaObjectsBasic.cpp). ### Modifiers and Keys The **``** field accepts one or more of: `SUPER`, `ALT`, `CTRL`, `SHIFT`, or `META`. Combine multiple modifiers with spaces (e.g., `SUPER SHIFT`). The **``** 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 **``** field determines what Hyprland executes when the binding activates. Common actions include: - **`exec`** – Run a shell command (requires command as ``) - **`kill`** – Close the focused window - **`togglefloating`** – Switch the focused window between tiled and floating - **`switchworkspace`** – Jump to a workspace (requires workspace number as ``) - **`movefocus`** – Change focus in a direction (requires direction `l`, `r`, `u`, `d` as ``) The **``** 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 **``** 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 ```conf # 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: ```conf # 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`](https://github.com/hyprwm/Hyprland/blob/main/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`](https://github.com/hyprwm/Hyprland/blob/main/src/managers/KeybindManager.cpp).