2024-02-20 21:16:07 +01:00
---
weight: 5
title: Binds
---
2022-09-24 15:32:40 +02:00
2024-02-20 21:16:07 +01:00
## Basic
2022-09-24 15:32:40 +02:00
2022-09-24 16:03:37 +02:00
```ini
2024-07-30 21:59:15 +02:00
bind = MODS, key, dispatcher, params
2022-09-24 15:32:40 +02:00
```
for example,
2022-09-24 16:03:37 +02:00
```ini
2024-07-30 21:59:15 +02:00
bind = SUPER_SHIFT, Q, exec, firefox
2022-09-24 15:32:40 +02:00
```
2024-04-21 16:35:48 +02:00
will bind opening Firefox to < key > SUPER< / key > + < key > SHIFT< / key > + < key > Q< / key >
2022-09-24 15:32:40 +02:00
2024-02-20 21:16:07 +01:00
{{< callout type = info > }}
2022-09-24 15:32:40 +02:00
For binding keys without a modkey, leave it empty:
2022-10-23 16:35:39 +02:00
2022-09-24 16:03:37 +02:00
```ini
2024-07-30 21:59:15 +02:00
bind = , Print, exec, grim
2022-09-24 15:32:40 +02:00
```
2022-10-23 16:35:39 +02:00
2024-02-20 21:16:07 +01:00
{{< / callout > }}
2022-09-24 15:32:40 +02:00
2024-03-17 13:44:39 +01:00
_For a complete mod list, see [Variables ](../Variables/#variable-types )._
2022-09-24 20:04:35 +02:00
2024-02-20 21:16:07 +01:00
_The dispatcher list can be found in
2024-03-17 13:44:39 +01:00
[Dispatchers ](../Dispatchers/#list-of-dispatchers )._
2022-09-24 15:32:40 +02:00
## Uncommon syms / binding with a keycode
See the
[xkbcommon-keysyms.h header ](https://github.com/xkbcommon/libxkbcommon/blob/master/include/xkbcommon/xkbcommon-keysyms.h )
2023-12-05 15:47:29 +01:00
for all the keysyms. The name you should use is the segment after `XKB_KEY_` .
2022-09-24 15:32:40 +02:00
2024-02-20 21:16:07 +01:00
If you are unsure of what your key's name is, you can use `xev` or `wev` to find
that information.
2022-09-24 15:32:40 +02:00
2024-04-21 16:35:48 +02:00
If you want to bind by a keycode, you can put it in the KEY position with
2024-02-20 21:16:07 +01:00
a `code:` prefix, e.g.:
2022-09-24 15:32:40 +02:00
2022-09-24 16:03:37 +02:00
```ini
2024-07-30 21:59:15 +02:00
bind = SUPER, code:28, exec, amongus
2022-09-24 15:32:40 +02:00
```
Will bind < key > SUPER< / key > + < key > T< / key > . (< key > T< / key > is keycode 28.) - You
can also use `xev` or `wev` to find keycodes.
2024-02-20 21:16:07 +01:00
## Misc
2022-10-23 16:35:39 +02:00
2024-11-06 19:34:37 +01:00
### Workspace bindings on non-qwerty layouts
2024-10-25 00:48:14 +02:00
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_key` s, 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 ](#uncommon-syms--binding-with-a-keycode )
{{< / callout > }}
```ini
# 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 ](https://rherault.dev/articles/hyprland-fr-layout ).
2024-02-20 21:16:07 +01:00
### Unbind
2022-09-24 15:32:40 +02:00
You can also unbind with `unbind` , e.g.:
2022-09-24 16:03:37 +02:00
```ini
2024-07-30 21:59:15 +02:00
unbind = SUPER, O
2022-09-24 15:32:40 +02:00
```
2024-07-30 21:59:15 +02:00
May be useful for dynamic keybindings with `hyprctl` :
2022-09-24 15:32:40 +02:00
2024-07-30 21:59:15 +02:00
```bash
hyprctl keyword unbind SUPER, O
2022-10-23 16:35:39 +02:00
```
2024-02-20 21:16:07 +01:00
### Mouse buttons
2022-10-23 16:35:39 +02:00
2022-09-24 15:32:40 +02:00
You can also bind mouse buttons, by prefacing the mouse keycode with `mouse:` ,
for example:
2022-09-24 16:03:37 +02:00
```ini
2024-07-30 21:59:15 +02:00
bind = SUPER, mouse:272, exec, amongus
2022-09-24 15:32:40 +02:00
```
will bind it to < key > SUPER< / key > + < key > LMB< / key > .
2024-02-20 21:16:07 +01:00
### Only modkeys
2022-10-23 16:35:39 +02:00
2024-07-25 14:13:57 +02:00
For binding only modkeys, you need to use the TARGET modmask (with the
2022-09-24 15:32:40 +02:00
activating mod) and the `r` flag, e.g.:
2022-09-24 16:03:37 +02:00
```ini
2024-07-30 21:59:15 +02:00
bindr = SUPER ALT, Alt_L, exec, amongus
2022-09-24 15:32:40 +02:00
```
2024-07-21 16:47:38 +02:00
Will bind `exec amongus` to < key > SUPER</ key > + < key > ALT</ key >
2024-05-16 12:48:05 +02:00
### Keysym combos
2024-06-13 23:19:47 +02:00
For an arbitrary combination of multiple keys, separate keysyms with `&` between
2024-05-16 12:48:05 +02:00
each mod/key and use the `s` flag, e.g.:
```ini
# 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.)
2024-02-20 21:16:07 +01:00
### Mouse wheel
2022-10-23 16:35:39 +02:00
2024-02-20 21:16:07 +01:00
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):
2022-10-23 16:35:39 +02:00
2022-09-24 16:03:37 +02:00
```ini
2024-07-30 21:59:15 +02:00
bind = SUPER, mouse_down, workspace, e-1
2022-09-24 15:32:40 +02:00
```
2022-10-23 16:35:39 +02:00
2022-09-24 15:32:40 +02:00
(control the reset time with `binds:scroll_event_delay` )
2024-02-20 21:16:07 +01:00
### Switches
2022-10-23 16:35:39 +02:00
2022-10-04 21:11:56 +02:00
Useful for binding e.g. the lid close/open event:
2022-10-23 16:35:39 +02:00
```ini
2023-01-17 13:41:55 +01:00
# trigger when the switch is toggled
2024-07-30 21:59:15 +02:00
bindl = , switch:[switch name], exec, swaylock
2023-01-08 16:35:51 +01:00
# trigger when the switch is turning on
2024-07-30 21:59:15 +02:00
bindl = , switch:on:[switch name], exec, hyprctl keyword monitor "eDP-1, disable"
2023-01-08 16:35:51 +01:00
# trigger when the switch is turning off
2024-07-30 21:59:15 +02:00
bindl = , switch:off:[switch name], exec, hyprctl keyword monitor "eDP-1, 2560x1600, 0x0, 1"
2022-10-04 21:11:56 +02:00
```
2022-10-23 16:35:39 +02:00
2024-04-21 16:35:48 +02:00
You can view your switches in `hyprctl devices` .
2022-10-04 21:11:56 +02:00
2024-02-20 21:16:07 +01:00
### Multiple binds to one key
2022-10-30 23:50:10 +01:00
2024-02-20 21:16:07 +01:00
You can trigger multiple actions with one keybind by assigning multiple binds to
one combination, e.g.:
2022-10-30 23:50:10 +01:00
2024-06-11 19:49:58 +02:00
```ini
2022-10-30 23:50:10 +01:00
# to switch between windows in a floating workspace
2024-07-30 21:59:15 +02:00
bind = SUPER, Tab, cyclenext, # change focus to another window
bind = SUPER, Tab, bringactivetotop, # bring it to the top
2022-10-30 23:50:10 +01:00
```
The keybinds will be executed in the order they were created. (top to bottom)
2024-06-11 19:49:58 +02:00
### 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 `,` !
```ini
2024-07-30 21:59:15 +02:00
bindd = MODS, key, description, dispatcher, params
2024-06-11 19:49:58 +02:00
```
for example,
```ini
2024-07-30 21:59:15 +02:00
bindd = SUPER, Q, Open my favourite terminal, exec, kitty
2024-06-11 19:49:58 +02:00
```
If you want to access your description you can use `hyprctl binds` . For more information have a look at [Using Hyprctl ](./Using-hyprctl.md ).
2024-02-20 21:16:07 +01:00
## Bind flags
2022-09-24 15:32:40 +02:00
2022-10-23 16:35:39 +02:00
`bind` supports flags in this format:
2022-09-24 15:32:40 +02:00
2022-09-24 16:03:37 +02:00
```ini
2024-07-30 21:59:15 +02:00
bind[flags] = ...
2022-09-24 15:32:40 +02:00
```
e.g.:
2022-09-24 16:03:37 +02:00
```ini
2024-07-30 21:59:15 +02:00
bindrl = MOD, KEY, exec, amongus
2022-09-24 15:32:40 +02:00
```
2022-10-23 16:35:39 +02:00
Flags:
2022-09-24 15:32:40 +02:00
2024-11-06 19:34:37 +01:00
```plain
2024-04-21 16:35:48 +02:00
l -> locked, will also work when an input inhibitor (e.g. a lockscreen) is active.
2023-06-14 13:09:27 +02:00
r -> release, will trigger on release of a key.
2024-11-16 00:22:15 +01:00
o -> longPress, will trigger on long press of a key.
2022-09-24 15:32:40 +02:00
e -> repeat, will repeat when held.
2023-06-14 13:09:27 +02:00
n -> non-consuming, key/mouse events will be passed to the active window in addition to triggering the dispatcher.
2024-06-13 23:19:47 +02:00
m -> mouse, see below.
2023-08-25 12:36:26 +02:00
t -> transparent, cannot be shadowed by other binds.
2023-10-17 21:10:49 +02:00
i -> ignore mods, will ignore modifiers.
2024-06-13 23:19:47 +02:00
s -> separate, will arbitrarily combine keys between each mod/key, see [Keysym combos ](#keysym-combos ) above.
2024-06-11 19:49:58 +02:00
d -> has description, will allow you to write a description for your bind.
2024-07-24 14:19:19 +02:00
p -> bypasses the app's requests to inhibit keybinds.
2022-09-24 15:32:40 +02:00
```
2022-10-23 16:35:39 +02:00
Example Usage:
```ini
2023-03-24 14:04:10 +01:00
# Example volume button that allows press and hold, volume limited to 150%
2024-07-30 21:59:15 +02:00
binde = , XF86AudioRaiseVolume, exec, wpctl set-volume -l 1.5 @DEFAULT_AUDIO_SINK @ 5%+
2022-10-23 16:35:39 +02:00
# Example volume button that will activate even while an input inhibitor is active
2024-07-30 21:59:15 +02:00
bindl = , XF86AudioLowerVolume, exec, wpctl set-volume @DEFAULT_AUDIO_SINK @ 5%-
2022-10-23 16:35:39 +02:00
# Start wofi opens wofi on first press, closes it on second
2024-08-16 18:21:22 +02:00
bindr = SUPER, SUPER_L, exec, pkill wofi || wofi
2022-10-23 16:35:39 +02:00
2024-06-11 19:49:58 +02:00
# Describe a bind
2024-07-30 21:59:15 +02:00
bindd = SUPER, Q, Open my favourite terminal, exec, kitty
2024-06-11 19:49:58 +02:00
2024-11-16 00:22:15 +01:00
# 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
```
2022-10-23 16:35:39 +02:00
2024-02-20 21:16:07 +01:00
## Mouse Binds
2022-10-23 16:35:39 +02:00
2024-04-21 16:35:48 +02:00
Mouse binds are binds that rely on mouse movement. They
will have one less arg, and may look like this:
2022-09-24 15:32:40 +02:00
2022-10-23 16:35:39 +02:00
```ini
2024-07-30 21:59:15 +02:00
bindm = ALT, mouse:272, movewindow
2022-09-24 15:32:40 +02:00
```
2024-04-21 16:35:48 +02:00
This will create a bind with < key > ALT< / key > + < key > LMB< / key > to move the window
2022-09-24 15:32:40 +02:00
with your mouse.
2022-10-23 16:35:39 +02:00
_Available mouse binds_:
2022-09-24 15:32:40 +02:00
2023-08-08 18:53:03 +02:00
| Name | Description | Params |
2024-02-20 21:16:07 +01:00
| --- | --- | --- |
| movewindow | moves the active window | none |
2023-08-08 18:53:03 +02:00
| 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 |
2022-09-24 15:32:40 +02:00
2022-10-23 16:35:39 +02:00
_Common mouse buttons' codes:_
```txt
2022-09-24 15:32:40 +02:00
LMB -> 272
RMB -> 273
```
2022-10-23 16:35:39 +02:00
_for more, you can of course use `wev` to check._
2022-09-24 15:32:40 +02:00
2024-02-20 21:16:07 +01:00
{{< callout type = info > }}
2022-09-24 15:32:40 +02:00
Mouse binds, despite their name, behave like normal binds. You are free to use
2024-02-20 21:16:07 +01:00
whatever keys / mods you please. When held, the mouse function will be
activated.
{{< / callout > }}
2022-09-24 15:32:40 +02:00
2024-04-24 23:46:40 +02:00
### Touchpad
As clicking and moving the mouse on a touchpad is unergonomic, you can also use keyboard keys instead of mouse clicks too.
```ini
2024-07-30 21:59:15 +02:00
bindm = SUPER, mouse:272, movewindow
bindm = SUPER, Control_L, movewindow
bindm = SUPER, mouse:273, resizewindow
bindm = SUPER, ALT_L, resizewindow
2024-04-24 23:46:40 +02:00
```
2024-02-20 21:16:07 +01:00
## Binding mods
2022-09-24 15:32:40 +02:00
You can bind a mod alone like this:
2022-09-24 16:03:37 +02:00
```ini
2024-07-30 21:59:15 +02:00
bindr = ALT,Alt_L,exec,amongus
2022-09-24 15:32:40 +02:00
```
2024-02-20 21:16:07 +01:00
## Global Keybinds
### Classic
2022-10-23 16:35:39 +02:00
2022-09-24 15:32:40 +02:00
Yes, you heard this right, Hyprland does support global keybinds for ALL apps,
including OBS, Discord, Firefox, etc.
2024-07-30 21:59:15 +02:00
See the [`pass` dispatcher ](../Dispatchers/#list-of-dispatchers ) and the
[`sendshortcut` dispatcher ](../Dispatchers/#list-of-dispatchers ) for keybinds.
2022-09-24 15:32:40 +02:00
2024-02-20 21:16:07 +01:00
Let's take OBS as an example: the "Start/Stop Recording" keybind is set to
2024-07-30 21:59:15 +02:00
< key > SUPER< / key > + < key > F10< / key > , and you want to make it work globally. Simply
add
2022-09-24 15:32:40 +02:00
2022-09-24 16:03:37 +02:00
```ini
2024-07-30 21:59:15 +02:00
bind = SUPER, F10, pass, ^(com\.obsproject\.Studio)$
2022-09-24 15:32:40 +02:00
```
2022-10-23 16:35:39 +02:00
2022-09-24 15:32:40 +02:00
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.:
2022-09-24 16:03:37 +02:00
```ini
2024-07-30 21:59:15 +02:00
bind = , mouse:276, pass, ^(TeamSpeak 3)$
2022-09-24 15:32:40 +02:00
```
Will pass MOUSE5 to TeamSpeak3.
2024-05-24 20:59:09 +02:00
You may also add shortcuts, where other keys are passed to the window.
```ini
2024-07-30 21:59:15 +02:00
bind = SUPER, F10, sendshortcut, SUPER, F4, ^(com\.obsproject\.Studio)$
2024-05-24 20:59:09 +02:00
```
2024-07-30 21:59:15 +02:00
Will send < key > SUPER< / key > + < key > F4< / key > to OBS if you press
< key > SUPER< / key > + < key > F10< / key > .
2024-05-24 20:59:09 +02:00
2024-02-20 21:16:07 +01:00
{{< callout > }}
2024-07-30 21:59:15 +02:00
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",
2024-04-21 16:35:48 +02:00
otherwise passing from a different XWayland app may not work.
2022-09-24 15:32:40 +02:00
2024-02-20 21:16:07 +01:00
{{< / callout > }}
### DBus Global Shortcuts
2023-04-11 00:02:23 +02:00
2024-02-20 21:16:07 +01:00
Some applications may already support the GlobalShortcuts portal in
xdg-desktop-portal.
2023-04-09 14:53:09 +02:00
If that's the case, then it's recommended to use this method instead of `pass` .
2024-07-30 21:59:15 +02:00
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).
2023-04-09 14:53:09 +02:00
2024-07-30 21:59:15 +02:00
Choose whichever you like, for example `coolApp:myToggle` , and bind it to
whatever you want with the `global` dispatcher:
2023-04-09 14:53:09 +02:00
2024-06-11 19:49:58 +02:00
```ini
2023-04-09 14:53:09 +02:00
bind = SUPERSHIFT, A, global, coolApp:myToggle
```
2024-02-20 21:16:07 +01:00
{{< callout type = info > }}
Please note that this function will _only_ work with
2024-03-17 13:44:39 +01:00
[XDPH ](../../Hypr-Ecosystem/xdg-desktop-portal-hyprland ).
2023-04-11 00:02:23 +02:00
2024-02-20 21:16:07 +01:00
{{< / callout > }}
## Submaps
2022-09-24 15:32:40 +02:00
2024-04-21 16:35:48 +02:00
Keybind submaps, also known as _modes_ or _groups_ , allow you to activate a
2024-11-06 19:34:37 +01:00
separate set of keybinds. For example, if you want to enter a "resize" mode
2024-04-21 16:35:48 +02:00
which allows you to resize windows with the arrow keys, you can do it like this:
2022-09-24 15:32:40 +02:00
2022-09-24 16:03:37 +02:00
```ini
2022-10-18 17:08:17 +02:00
# will switch to a submap called resize
2024-07-30 21:59:15 +02:00
bind = ALT, R, submap, resize
2022-09-24 15:32:40 +02:00
2022-10-18 17:08:17 +02:00
# will start a submap called "resize"
2024-07-30 21:59:15 +02:00
submap = resize
2022-09-24 15:32:40 +02:00
2022-10-18 17:08:17 +02:00
# sets repeatable binds for resizing the active window
2024-07-30 21:59:15 +02:00
binde = , right, resizeactive, 10 0
binde = , left, resizeactive, -10 0
binde = , up, resizeactive, 0 -10
binde = , down, resizeactive, 0 10
2022-09-24 15:32:40 +02:00
2022-10-18 17:08:17 +02:00
# use reset to go back to the global submap
2024-07-30 21:59:15 +02:00
bind = , escape, submap, reset
2022-09-24 15:32:40 +02:00
2024-04-21 16:35:48 +02:00
# will reset the submap, which will return to the global submap
2024-07-30 21:59:15 +02:00
submap = reset
2022-09-24 15:32:40 +02:00
# keybinds further down will be global again...
```
2024-02-20 21:16:07 +01:00
{{< callout type = warning > }}
Do not forget a keybind to reset the keymap while inside it! (In this case,
`escape` )
{{< / callout > }}
2022-09-24 15:32:40 +02:00
If you get stuck inside a keymap, you can use `hyprctl dispatch submap reset` to
2024-02-20 21:16:07 +01:00
go back. If you do not have a terminal open, tough luck buddy. You have been
warned.
2022-10-18 17:08:17 +02:00
You can also set the same keybind to perform multiple actions, such as resize
and close the submap, like so:
```ini
2024-07-30 21:59:15 +02:00
bind = ALT, R, submap, resize
2022-10-18 17:08:17 +02:00
2024-07-30 21:59:15 +02:00
submap = resize
2022-10-18 17:08:17 +02:00
2024-07-30 21:59:15 +02:00
bind = , right, resizeactive, 10 0
bind = , right, submap, reset
2022-10-18 17:08:17 +02:00
# ...
2024-07-30 21:59:15 +02:00
submap = reset
2022-10-18 17:08:17 +02:00
```
This works because the binds are executed in the order they appear, and
assigning multiple actions per bind is possible.
2024-02-13 20:11:37 +01:00
2024-03-03 04:23:13 +01:00
## Catch-All
2024-02-20 21:16:07 +01:00
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:
2024-03-03 04:23:13 +01:00
```ini
2024-07-30 21:59:15 +02:00
bind = , catchall, submap, reset
2024-03-03 04:23:13 +01:00
```
2024-02-20 21:16:07 +01:00
## Example Binds
2024-02-13 20:11:37 +01:00
2024-02-20 21:16:07 +01:00
### Media
2024-02-13 20:11:37 +01:00
These binds set the expected behavior for regular keyboard media volume keys,
including when the screen is locked:
```ini
2024-07-30 21:59:15 +02:00
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
2024-07-07 15:10:14 +02:00
# Requires playerctl
2024-07-30 21:59:15 +02:00
bindl = , XF86AudioPlay, exec, playerctl play-pause
bindl = , XF86AudioPrev, exec, playerctl previous
bindl = , XF86AudioNext, exec, playerctl next
2024-02-13 20:11:37 +01:00
```