Modes

INFO

This page is for people creating custom keybindings or scripts. To learn how to move windows with the built-in placement mode, see Layouts.

Modes in instantWM work like Sway/i3 modes: each mode is a set of keybindings that is only active while that mode is on. Use them for tasks like resizing windows, navigating scratchpads, or running specific commands.

Defining a mode

Mode bindings use the same key and action syntax as normal bindings:

[modes.resize]
description = "Resize"

[[modes.resize.keybinds]]
modifiers = []
key = "h"
action = "key_resize_left"

[[modes.resize.keybinds]]
modifiers = []
key = "j"
action = "key_resize_down"

[[modes.resize.keybinds]]
modifiers = []
key = "k"
action = "key_resize_up"

[[modes.resize.keybinds]]
modifiers = []
key = "l"
action = "key_resize_right"

[[modes.resize.keybinds]]
modifiers = []
key = "Escape"
action = { set_mode = "default" }

[[modes.resize.keybinds]]
modifiers = []
key = "Return"
action = { set_mode = "default" }

Bind another key to enter it:

[[keybinds]]
modifiers = ["Super"]
key = "r"
action = { set_mode = "resize" }

The description is displayed in the bar in place of the internal name. Use { set_mode = "default" } to leave any custom mode. Changing modes also cancels anything the previous mode had in progress, such as a placement preview.

Named modes fall back to global and desktop bindings when they do not override a key. Set transient = true on a mode to return to Default after any matched mode/global binding executes:

[modes.launch]
description = "Launch"
transient = true

Customizing the built-in placement mode

super+m starts instantWM's built-in placement mode for a tiled window which has another valid destination.

The defaults are arrows or h/j/k/l to choose a target, Shift plus a direction to swap, Ctrl plus a direction to resize, Tab/Shift+Tab to cycle targets, Space for a centre swap, Enter to apply, and Escape to cancel. An unrelated key also cancels without being delivered to the focused application.

These are ordinary named actions, so you can replace the built-in bindings:

[modes.placement]
description = "Place window"

[[modes.placement.keybinds]]
modifiers = []
key = "a"
action = "placement_left"

[[modes.placement.keybinds]]
modifiers = []
key = "d"
action = "placement_right"

Useful names include placement_left, placement_right, placement_up, placement_down, their placement_swap_* and placement_resize_* variants, and placement_next, placement_previous, placement_center, placement_apply, and placement_cancel. If you remove a placement binding, pressing that key cancels the mode.

Implementation note

IPC can list the active placement mode and leave it by changing modes, but mode set placement cannot enter it, because placement needs a source window and a set of targets. Invoke the begin_tree_placement action instead.

Command-line control

instantwmctl mode list
instantwmctl mode set resize
instantwmctl mode toggle resize
instantwmctl mode set default

Use instantwm --list-actions or instantwmctl action --list to see the action names supported by the installed build.

See Layouts for placement behavior and instantWM configuration for binding syntax.