Can be used with an xkb lv5 option like lv5:caps_switch
Mod
Special modifier: Super on TTY, Alt in nested window
Mod is a special modifier that is equal to Super when running niri on a TTY, and to Alt when running niri as a nested winit window. This way, you can test niri in a window without causing too many conflicts with the host compositor’s key bindings. You can customize the Mod key in the input section of the config.
Binding shifted keys requires spelling out Shift and the unshifted version of the key, according to your XKB layout.For example, on US QWERTY, < is on Shift + ,, so to bind it, you spell out Mod+Shift+Comma.
Spawn bindings have a special allow-when-locked=true property that makes them work even while the session is locked:
binds { // This mute bind will work even when the session is locked. XF86AudioMute allow-when-locked=true { spawn "wpctl" "set-mute" "@DEFAULT_AUDIO_SINK@" "toggle"; }}
You can make certain binds ignore inhibiting with the allow-inhibiting=false property. They will always be handled by niri and never passed to the window.
binds { // This bind will always work, even when using a virtual machine. Super+Alt+L allow-inhibiting=false { spawn "swaylock"; }}
Similarly, you can bind touchpad scroll “ticks”. Touchpad scrolling is continuous, so for these binds it is split into discrete intervals based on distance travelled.
Both mouse wheel and touchpad scroll binds will prevent applications from receiving any scroll events when their modifiers are held down. For example, if you have a Mod+WheelScrollDown bind, then while holding Mod, all mouse wheel scrolling will be consumed by niri.
The hotkey overlay (the Important Hotkeys dialog) shows a hardcoded list of binds. You can customize this list using the hotkey-overlay-title property.
For spawn, niri does not use a shell to run commands, which means that you need to manually separate arguments.
// Correct: every argument is in its own quotes.Mod+T { spawn "alacritty" "-e" "/usr/bin/fish"; }// Wrong: will interpret the whole string as the binary path.Mod+D { spawn "alacritty -e /usr/bin/fish"; }
Shell Expansion
This also means that you cannot expand environment variables or ~. If you need this, you can run the command through a shell manually.
binds { // Wrong: no shell expansion here. Mod+T { spawn "grim" "-o" "$MAIN_OUTPUT" "~/screenshot.png"; } // Correct: run through a shell for expansion. Mod+D { spawn "sh" "-c" "grim -o $MAIN_OUTPUT ~/screenshot.png"; }}
As a special case, niri will expand ~ to the home directory only at the beginning of the program name:
spawn-sh "some command" is equivalent to spawn "sh" "-c" "some command"—it’s just a less confusing shorthand.Keep in mind that going through the shell incurs a tiny performance penalty compared to directly spawning some binary.
Applications such as remote-desktop clients and software KVM switches may request that niri stops processing its keyboard shortcuts. toggle-keyboard-shortcuts-inhibit is an escape hatch that toggles the inhibitor.