Keybinding Options

Keybindings are configured under the [bindings] table. They can be configured in two formats: array format, and table format.

Array Format:

"Key1+Key2" = ["Action", "Argument"] # There can be multiple arguments.

All the elements in this array must always be a string.

Table Format:

"Key1+Key2" = {
    action = "Action",
    arg = "Argument"
}

This format can be used when more advanced configuration is needed. For example, disabling repeat for this binding.

Modifier Keys

There are four modifier keys:

  • Super or Mod4: The windows logo key.

  • Alt or Mod1: The alt key.

  • Ctrl or Control: The control key.

  • Shift: The shift key.

  • ADPT: Adaptive key that chooses between Super and Alt based on whether the compositor is running nested or not.

These keys can be paired with keys to get a keybinding. Example: Super+Return. The key names are provided by xkbcommon, so you should follow those names for the keybinding to function. This is why Return is used instead of Enter. It is case insensitive, so something like super+return works too.

The paired keys can also be a keycode. They should be in the code:<number> format. Like this: super+code:24. The keycode must be the raw scancode for the desired key used in the linux kernel.

Actions

Each keybinding can peform an action, whether that be running a shell command, closing an application, or switching the workspace. As shown above, they are an array or table like so:

# Array Version
kb = ["Action", "Argument"]

# Table Version
kb = {
    action = "Action",
    arg = "Argument"
}

spawn

This is the most common action. It is used to spawn a shell command. The shell command to execute must be the argument.

Example:

[bindings]
# Format: keybinding = ["Action", "Argument"]
"Super+Return" = ["spawn", "kitty"]

close-active-window

Close the currently active window. Takes no argument.

Example:

[bindings]
"Super+Q" = ["close-active-window"]

focus-window

Focus a window. Takes the direction as an argument. Available directions:

  • "up"

  • "down"

  • "left"

  • "right"

Example:

[bindings]
"Super+Right" = ["focus-window", "right"]

move-window

Move the focused window. Takes a direction as an argument (same options as focus-window).

Example:

[bindings]
"Super+Shift+Right" = ["move-window", "right"]

window-to-workspace

Move the focused window to a workspace. Takes the workspace index to move to as the argument.

Example:

[bindings]
"Super+Shift+1" = ["window-to-workspace", 1]

switch-workspace

Switch the currently active workspace. The argument should be the workspace number.

Example:

[bindings]
"Super+1" = ["switch-workspace", "1"]

toggle-monocle

Toggle the monocle layout. Takes no argument.

Example:

[bindings]
"Super+M" = ["toggle-monocle"]

cycle-monocle

Cycle to the next window in the monocle. Takes no argument.

Example:

[bindings]
"Super+J" = ["cycle-monocle"]

quit-compositor

Quit the compositor. Takes no argument.

Example:

[bindings]
"Super+Escape" = ["quit-compositor"]

Keybinding Configuration

A keybinding can be configured if you are using the table format. This section will cover all the options you can configure inside a table.

kb = {
    action = "Action",
    arg = "Argument",
    # other options here...
}

repeat

Whether to allow repeat for this keybinding (boolean). Default is true.

kb = {
    # ..
    repeat = false
}