Skip to content
Menu

Guides

Examples

Configuration recipes: modes, prefix keys, layouts per workspace, rules, scripts, events and gestures.

A complete configuration in use, with binds, a prefix key, binding modes, window rules and layouts, is in the author’s dotfiles: config/wm/init.lua. It is a good place to see how the pieces below fit together.

A resize mode with a key panel

wm.mode("resize", {
  h = { "resize width +50", description = "Wider" },
  l = { "resize width -50", description = "Narrower" },
  j = { "resize height +50", description = "Taller" },
  k = { "resize height -50", description = "Shorter" },
  esc = { "mode main", description = "Exit" },
})
wm.bind("alt-shift-r", "mode resize")

While the mode is active, a panel lists its keys with the text from description. See The key panel.

wm.mode(name, binds, options) takes options as its third argument:

Option What it does
once = true The mode ends after the first bind of it has run, and the mode before it is back. A bind that goes to another mode itself keeps that mode.
swallow = true A key that the mode does not bind is not typed into the app. Without it, such keys go on to the app (a hyper chord with no bind is always swallowed).

wm mode back (or wm.dispatch("mode back")) goes back to the mode before the current one. wm keeps the last 8 modes, and mode main forgets them. back is not a name for a mode.

wm.mode("focus", { h = "focus left", l = "focus right", j = "focus down", k = "focus up" }, { once = true, swallow = true })
wm.bind("alt-f", "mode focus")   -- alt-f, then one of h j k l, and the mode is over

One prefix key, then a letter

local PREFIX = "alt-space>"
wm.bind(PREFIX .. "h", "focus left")
wm.bind(PREFIX .. "l", "focus right")
wm.bind(PREFIX .. "f", "window fullscreen")
wm.bind(PREFIX .. "tab", "switcher")

After alt-space, wm waits for the next key (or Escape) and shows the keys that can follow.

A different layout per workspace and per monitor

wm.workspace("1", { layout = "scrolling" })
wm.workspace("2", { layout = "tiling" })
wm.workspace("web", { monitor = 2, default = true, gaps = { inner = 0, outer = 0 }, border = false })
wm.workspace("code", { layout = "scrolling", monitor = "LG", layout_options = { default_width = 0.7 } })

Window rules

wm.rule { app = "com.apple.systempreferences", float = true }
wm.rule { app = "net.kovidgoyal.kitty", float = true, size = { 0.62, 0.68 }, center = true }
wm.rule { title = "^Picture in Picture$", float = true }
wm.rule { app = "com.spotify.client", workspace = "9" }
wm.rule { app = "com.apple.Notes", monitor = 2, width = 0.4, focus = false }

Scripts from the shell

wm list windows                                   # a table of every window
wm list windows --focused --json                  # JSON for scripts
wm pick                                           # click a window: its id, app, title and a wm.rule for it
wm --window app:com.apple.Notes window close      # act on a window by app, title or pid
wm batch 'workspace 2; layout set tiling'         # several commands, stops at the first error
wm set gaps.inner 4                               # change a config value until the next reload
wm notify 'build done' --seconds=3                # a message on screen

React to events

wm.on("workspace_changed", function(e) wm.log("now on workspace " .. e.workspace) end)
wm.on("window_open", { app = "com.apple.finder" }, function(e)
  wm.dispatch("window float", { window = e.id })
end)

Swipe gestures

wm.gesture { mods = "alt", direction = "left",  command = "workspace prev", description = "Previous workspace" }
wm.gesture { mods = "alt", direction = "right", command = "workspace next" }