Actions overview

You will learn

• How to bind actions to hotkeys
• What action categories exist
• How to use layout-specific actions

Actions are operations bound to hotkeys. Shoji ships with built-in actions for navigation, window management, and layout control.

This page explains how actions work. For the canonical list of actions and defaults, see Actions reference.

Action categories

• Navigation - Move focus between windows
• Window management - Swap positions and toggle floating
• Layout control - Switch layouts and tweak parameters

Binding actions

Use bindHotkeys to assign actions to key combinations:

spoon.Shoji:bindHotkeys({
  focus_left = { { "ctrl", "alt" }, "h" },
  focus_right = { { "ctrl", "alt" }, "l" },
  cycle_layout = { { "ctrl", "alt" }, "space" },
})

Default hotkeys

Shoji binds default hotkeys automatically when you call start(). See Default keybindings for the full list.

To override defaults, call bindHotkeys before start():

spoon.Shoji:bindHotkeys({
  focus_left = { { "ctrl", "alt" }, "h" },
  focus_right = { { "ctrl", "alt" }, "l" },
})
spoon.Shoji:start()

Hotkey format

Either format works:

-- Standard Spoon format: { modifiers_table, key }
focus_left = { { "ctrl", "alt" }, "h" }

-- Flat format: all strings in one table, key comes last
focus_left = { "ctrl", "alt", "h" }

Available modifiers

Modifier	Key name
Command	"cmd"
Control	"ctrl"
Option/Alt	"alt"
Shift	"shift"
Function	"fn"

Disabling specific actions

Pass an empty table to skip binding an action:

spoon.Shoji:bindHotkeys({
  focus_left = { { "ctrl", "alt" }, "h" },
  focus_right = {},  -- Not bound
})

Layout-specific actions

Some layouts expose their own actions. BSP, for example, provides resize and rotate:

spoon.Shoji:bindHotkeys({
  bsp_expand_horizontal = { { "ctrl", "cmd" }, "l" },
  bsp_shrink_horizontal = { { "ctrl", "cmd" }, "h" },
  bsp_expand_vertical = { { "ctrl", "cmd" }, "j" },
  bsp_shrink_vertical = { { "ctrl", "cmd" }, "k" },
  bsp_rotate = { { "ctrl", "cmd" }, "r" },
})

Layout actions follow the pattern <layout>_<action>.

Unbinding all hotkeys

spoon.Shoji:unbindHotkeys()

Removes every hotkey binding created by bindHotkeys. Useful for stopping Shoji or switching between keybinding sets.

Full list

For the complete list of action names and defaults, see Actions reference.