hyprland-wiki/pages/Configuring/Binds.md

weight	title
5	Binds

Basic

bind = MODS, key, dispatcher, params

for example,

bind = SUPER_SHIFT, Q, exec, firefox

will bind opening Firefox to SUPER + SHIFT + Q

{{< callout type=info >}}

For binding keys without a modkey, leave it empty:

bind = , Print, exec, grim

{{< /callout >}}

For a complete mod list, see Variables.

The dispatcher list can be found in Dispatchers.

Uncommon syms / binding with a keycode

See the xkbcommon-keysyms.h header for all the keysyms. The name you should use is the segment after XKB_KEY_.

If you are unsure of what your key's name is, you can use xev or wev to find that information.

If you want to bind by a keycode, you can put it in the KEY position with a code: prefix, e.g.:

bind = SUPER, code:28, exec, amongus

Will bind SUPER + T. (T is keycode 28.) - You can also use xev or wev to find keycodes.

Misc

Workspace bindings on non-qwerty layouts

Keys used for keybinds need to be accessible without any modifiers in your layout. For instance, the French Azerty layout uses SHIFT+unmodified_key to write 0-9 numbers. As such, the workspace keybinds for this layout need to use the names of the unmodified_keys, and will not work when using the 0-9 numbers.

{{< callout type=info >}}

To get the correct name for an unmodified_key, refer to the section on uncommon syms

{{< /callout >}}

# On a french layout, instead of
# bind = $mainMod, 1, workspace,  1

# Use 
bind = $mainMod, ampersand, workspace,  1

For help configuring the French Azerty layout, see.

Unbind

You can also unbind with unbind, e.g.:

unbind = SUPER, O

May be useful for dynamic keybindings with hyprctl:

hyprctl keyword unbind SUPER, O

Mouse buttons

You can also bind mouse buttons, by prefacing the mouse keycode with mouse:, for example:

bind = SUPER, mouse:272, exec, amongus

will bind it to SUPER + LMB.

Only modkeys

For binding only modkeys, you need to use the TARGET modmask (with the activating mod) and the r flag, e.g.:

bindr = SUPER ALT, Alt_L, exec, amongus

Will bind exec amongus to SUPER + ALT

Keysym combos

For an arbitrary combination of multiple keys, separate keysyms with & between each mod/key and use the s flag, e.g.:

# You can use a single mod with multiple keys.
binds = Control_L, A&Z, exec, kitty
# You can also specify multiple specific mods.
binds = Control_L&Shift_L, K, exec, kitty
# You can also do both!
binds = Control_R&Super_R&Alt_L, J&K&L, exec, kitty
# If you are feeling a little wild... you can use other keys for binds...
binds = Escape&Apostrophe&F7, T&O&A&D, exec, battletoads 2: retoaded

(Please note this is only valid for keysyms and it makes all mods keysyms. If you don't know what a keysym is use xev and press the key you want to use.)

Mouse wheel

You can also bind the mouse wheel with mouse_up and mouse_down (or mouse_left and mouse_right if your wheel supports horizontal scrolling):

bind = SUPER, mouse_down, workspace, e-1

(control the reset time with binds:scroll_event_delay)

Switches

Useful for binding e.g. the lid close/open event:

# trigger when the switch is toggled
bindl = , switch:[switch name], exec, swaylock
# trigger when the switch is turning on
bindl = , switch:on:[switch name], exec, hyprctl keyword monitor "eDP-1, disable"
# trigger when the switch is turning off
bindl = , switch:off:[switch name], exec, hyprctl keyword monitor "eDP-1, 2560x1600, 0x0, 1"

You can view your switches in hyprctl devices.

Multiple binds to one key

You can trigger multiple actions with one keybind by assigning multiple binds to one combination, e.g.:

# to switch between windows in a floating workspace
bind = SUPER, Tab, cyclenext,           # change focus to another window
bind = SUPER, Tab, bringactivetotop,    # bring it to the top

The keybinds will be executed in the order they were created. (top to bottom)

Description

You can describe your keybind with the description flag. Your description always goes in front of the dispatcher and should never contain the character ,!

bindd = MODS, key, description, dispatcher, params

for example,

bindd = SUPER, Q, Open my favourite terminal, exec, kitty

If you want to access your description you can use hyprctl binds. For more information have a look at Using Hyprctl.

Bind flags

bind supports flags in this format:

bind[flags] = ...

e.g.:

bindrl = MOD, KEY, exec, amongus

Flags:

l -> locked, will also work when an input inhibitor (e.g. a lockscreen) is active.
r -> release, will trigger on release of a key.
o -> longPress, will trigger on long press of a key.
e -> repeat, will repeat when held.
n -> non-consuming, key/mouse events will be passed to the active window in addition to triggering the dispatcher.
m -> mouse, see below.
t -> transparent, cannot be shadowed by other binds.
i -> ignore mods, will ignore modifiers.
s -> separate, will arbitrarily combine keys between each mod/key, see [Keysym combos](#keysym-combos) above.
d -> has description, will allow you to write a description for your bind.
p -> bypasses the app's requests to inhibit keybinds.

Example Usage:

# Example volume button that allows press and hold, volume limited to 150%
binde = , XF86AudioRaiseVolume, exec, wpctl set-volume -l 1.5 @DEFAULT_AUDIO_SINK@ 5%+

# Example volume button that will activate even while an input inhibitor is active
bindl = , XF86AudioLowerVolume, exec, wpctl set-volume @DEFAULT_AUDIO_SINK@ 5%-

# Start wofi opens wofi on first press, closes it on second
bindr = SUPER, SUPER_L, exec, pkill wofi || wofi

# Describe a bind
bindd = SUPER, Q, Open my favourite terminal, exec, kitty

# Skip player on long press and only skip 5s on normal press
bindo = SUPER, XF86AudioNext, exec, playerctl next
bind = SUPER, XF86AudioNext, exec, playerctl position +5

Mouse Binds

Mouse binds are binds that rely on mouse movement. They will have one less arg, and may look like this:

bindm = ALT, mouse:272, movewindow

This will create a bind with ALT + LMB to move the window with your mouse.

Available mouse binds:

Name	Description	Params
movewindow	moves the active window	none
resizewindow	resizes the active window	1 - resize and keep window aspect ratio, 2 - resize and ignore keepaspectratio window rule/prop, none or anything else for normal resize

Common mouse buttons' codes:

LMB -> 272
RMB -> 273

for more, you can of course use wev to check.

{{< callout type=info >}}

Mouse binds, despite their name, behave like normal binds. You are free to use whatever keys / mods you please. When held, the mouse function will be activated.

{{< /callout >}}

Touchpad

As clicking and moving the mouse on a touchpad is unergonomic, you can also use keyboard keys instead of mouse clicks too.

bindm = SUPER, mouse:272, movewindow
bindm = SUPER, Control_L, movewindow
bindm = SUPER, mouse:273, resizewindow
bindm = SUPER, ALT_L, resizewindow

Binding mods

You can bind a mod alone like this:

bindr = ALT,Alt_L,exec,amongus

Global Keybinds

Classic

Yes, you heard this right, Hyprland does support global keybinds for ALL apps, including OBS, Discord, Firefox, etc.

See the pass dispatcher and the sendshortcut dispatcher for keybinds.

Let's take OBS as an example: the "Start/Stop Recording" keybind is set to SUPER + F10, and you want to make it work globally. Simply add

bind = SUPER, F10, pass, ^(com\.obsproject\.Studio)$

to your config and you're done.

pass will pass the PRESS and RELEASE events by itself, no need for a bindr. This also means that push-to-talk will work flawlessly with one pass, e.g.:

bind = , mouse:276, pass, ^(TeamSpeak 3)$

Will pass MOUSE5 to TeamSpeak3.

You may also add shortcuts, where other keys are passed to the window.

bind = SUPER, F10, sendshortcut, SUPER, F4, ^(com\.obsproject\.Studio)$

Will send SUPER + F4 to OBS if you press SUPER + F10.

{{< callout >}}

This works flawlessly with all native Wayland applications. However, XWayland is a bit wonky. Make sure that what you're passing is a "global Xorg keybind", otherwise passing from a different XWayland app may not work.

{{< /callout >}}

DBus Global Shortcuts

Some applications may already support the GlobalShortcuts portal in xdg-desktop-portal.

If that's the case, then it's recommended to use this method instead of pass.

Open your desired app and run hyprctl globalshortcuts in a terminal. This will give you a list of currently registered shortcuts with their description(s).

Choose whichever you like, for example coolApp:myToggle, and bind it to whatever you want with the global dispatcher:

bind = SUPERSHIFT, A, global, coolApp:myToggle

{{< callout type=info >}}

Please note that this function will only work with XDPH.

{{</ callout >}}

Submaps

Keybind submaps, also known as modes or groups, allow you to activate a separate set of keybinds. For example, if you want to enter a "resize" mode which allows you to resize windows with the arrow keys, you can do it like this:

# will switch to a submap called resize
bind = ALT, R, submap, resize

# will start a submap called "resize"
submap = resize

# sets repeatable binds for resizing the active window
binde = , right, resizeactive, 10 0
binde = , left, resizeactive, -10 0
binde = , up, resizeactive, 0 -10
binde = , down, resizeactive, 0 10

# use reset to go back to the global submap
bind = , escape, submap, reset 

# will reset the submap, which will return to the global submap
submap = reset

# keybinds further down will be global again...

{{< callout type=warning >}}

Do not forget a keybind to reset the keymap while inside it! (In this case, escape)

{{< /callout >}}

If you get stuck inside a keymap, you can use hyprctl dispatch submap reset to go back. If you do not have a terminal open, tough luck buddy. You have been warned.

You can also set the same keybind to perform multiple actions, such as resize and close the submap, like so:

bind = ALT, R, submap, resize

submap = resize

bind = , right, resizeactive, 10 0
bind = , right, submap, reset
# ...

submap = reset

This works because the binds are executed in the order they appear, and assigning multiple actions per bind is possible.

Catch-All

You can also define a keybind via the special catchall keyword, which activates no matter which key is pressed. This can be used to prevent any keys from passing to your active application while in a submap or to exit it immediately when any unknown key is pressed:

bind = , catchall, submap, reset

Example Binds

Media

These binds set the expected behavior for regular keyboard media volume keys, including when the screen is locked:

bindel = , XF86AudioRaiseVolume, exec, wpctl set-volume @DEFAULT_AUDIO_SINK@ 5%+
bindel = , XF86AudioLowerVolume, exec, wpctl set-volume @DEFAULT_AUDIO_SINK@ 5%-
bindl = , XF86AudioMute, exec, wpctl set-mute @DEFAULT_AUDIO_SINK@ toggle
# Requires playerctl
bindl = , XF86AudioPlay, exec, playerctl play-pause
bindl = , XF86AudioPrev, exec, playerctl previous
bindl = , XF86AudioNext, exec, playerctl next