Actions reference
Actions that can be bound to hotkeys or called directly from Lua. This page is the canonical list of actions and defaults. For behavior guides and examples, see Actions overview.
Usage
Bind actions to hotkeys using bindHotkeys():
spoon.Shoji:bindHotkeys({ focus_left = { { "ctrl", "alt" }, "h" }, swap_main = { { "ctrl", "alt" }, "return" },})Both formats are supported:
-- Standard Spoon format (recommended)focus_left = { { "ctrl", "alt" }, "h" }
-- Flat formatfocus_left = { "ctrl", "alt", "h" }Navigation actions
Move focus between windows.
focus_left
Focus the window to the left.
focus_left = { { "ctrl", "alt" }, "h" }focus_right
Focus the window to the right.
focus_right = { { "ctrl", "alt" }, "l" }focus_up
Focus the window above.
focus_up = { { "ctrl", "alt" }, "k" }focus_down
Focus the window below.
focus_down = { { "ctrl", "alt" }, "j" }focus_next
Focus the next window in order. Wraps to the first window after the last.
focus_next = { { "ctrl", "alt" }, "n" }focus_prev
Focus the previous window in order. Wraps to the last window before the first.
focus_prev = { { "ctrl", "alt" }, "p" }focus_previous
Focus the previously focused window (history).
focus_previous = { { "ctrl", "alt" }, "tab" }Window management actions
Swap windows or toggle floating state.
swap_left
Swap the focused window with the one to its left.
swap_left = { { "ctrl", "alt", "shift" }, "h" }swap_right
Swap the focused window with the one to its right.
swap_right = { { "ctrl", "alt", "shift" }, "l" }swap_up
Swap the focused window with the one above it.
swap_up = { { "ctrl", "alt", "shift" }, "k" }swap_down
Swap the focused window with the one below it.
swap_down = { { "ctrl", "alt", "shift" }, "j" }swap_next
Swap the focused window with the next one in order.
swap_next = { { "ctrl", "alt", "shift" }, "n" }swap_prev
Swap the focused window with the previous one in order.
swap_prev = { { "ctrl", "alt", "shift" }, "p" }swap_main
Swap the focused window with the first (main) window.
swap_main = { { "ctrl", "alt" }, "return" }toggle_float
Toggle floating state for the focused window. Floating windows are excluded from tiling and can be positioned freely. When toggled back, the window rejoins the tile order as a new entry (typically at the end).
toggle_float = { { "ctrl", "alt", "shift" }, "t" }Layout control actions
Change layouts and adjust layout parameters.
cycle_layout
Cycle to the next layout in enabled_layouts.
cycle_layout = { { "ctrl", "alt" }, "space" }increase_main_ratio
Increase the main area ratio by 0.05.
increase_main_ratio = { { "ctrl", "alt" }, "=" }decrease_main_ratio
Decrease the main area ratio by 0.05.
decrease_main_ratio = { { "ctrl", "alt" }, "-" }increase_nmaster
Increase the number of master windows by 1.
increase_nmaster = { { "ctrl", "alt" }, "," }decrease_nmaster
Decrease the number of master windows by 1 (minimum 1).
decrease_nmaster = { { "ctrl", "alt" }, "." }retile_space
Retile the current space and reset layout parameters (ratio, nmaster) to their defaults.
retile_space = { { "ctrl", "alt", "shift" }, "r" }Direct layout actions
Switch directly to a specific layout without cycling.
set_layout_<name>
Switch to a specific layout by name. Available for all registered layouts.
set_layout_tall = { { "ctrl", "alt" }, "1" }set_layout_wide = { { "ctrl", "alt" }, "2" }set_layout_bsp = { { "ctrl", "alt" }, "3" }set_layout_fullscreen = { { "ctrl", "alt" }, "4" }set_layout_grid = { { "ctrl", "alt" }, "5" }set_layout_floating = { { "ctrl", "alt" }, "0" }BSP layout actions
These actions only take effect when BSP (binary space partitioning) is active.
bsp_shrink_horizontal
Shrink the focused window horizontally.
bsp_shrink_horizontal = { { "ctrl", "cmd" }, "h" }bsp_expand_horizontal
Expand the focused window horizontally.
bsp_expand_horizontal = { { "ctrl", "cmd" }, "l" }bsp_shrink_vertical
Shrink the focused window vertically.
bsp_shrink_vertical = { { "ctrl", "cmd" }, "k" }bsp_expand_vertical
Expand the focused window vertically.
bsp_expand_vertical = { { "ctrl", "cmd" }, "j" }bsp_rotate
Rotate all splits by 90 degrees, swapping horizontal and vertical directions.
bsp_rotate = { { "ctrl", "cmd" }, "r" }Default hotkeys
Apply all default bindings at once:
spoon.Shoji:bindHotkeys( spoon.Shoji.actions.DEFAULT_HOTKEYS)Default bindings use Ctrl+Alt as the primary modifier to avoid conflicts with Option key special characters on macOS:
focus_left: Ctrl+Alt+Hfocus_right: Ctrl+Alt+Lfocus_up: Ctrl+Alt+Kfocus_down: Ctrl+Alt+Jfocus_next: Ctrl+Alt+Nfocus_prev: Ctrl+Alt+Pfocus_previous: Ctrl+Alt+Tabswap_left: Ctrl+Alt+Shift+Hswap_right: Ctrl+Alt+Shift+Lswap_up: Ctrl+Alt+Shift+Kswap_down: Ctrl+Alt+Shift+Jswap_next: Ctrl+Alt+Shift+Nswap_prev: Ctrl+Alt+Shift+Pswap_main: Ctrl+Alt+Returntoggle_float: Ctrl+Alt+Shift+Tcycle_layout: Ctrl+Alt+Spaceincrease_main_ratio: Ctrl+Alt+=decrease_main_ratio: Ctrl+Alt+-increase_nmaster: Ctrl+Alt+,decrease_nmaster: Ctrl+Alt+.retile_space: Ctrl+Alt+Shift+Rbsp_shrink_horizontal: Ctrl+Cmd+Hbsp_expand_horizontal: Ctrl+Cmd+Lbsp_shrink_vertical: Ctrl+Cmd+Kbsp_expand_vertical: Ctrl+Cmd+Jbsp_rotate: Ctrl+Cmd+R
Calling actions directly
Call actions from Lua without hotkeys:
-- Focus actionsspoon.Shoji.actions.focusLeft()spoon.Shoji.actions.focusRight()spoon.Shoji.actions.focusUp()spoon.Shoji.actions.focusDown()spoon.Shoji.actions.focusNext()spoon.Shoji.actions.focusPrev()spoon.Shoji.actions.focusPrevious() -- History-based
-- Swap actionsspoon.Shoji.actions.swapLeft()spoon.Shoji.actions.swapRight()spoon.Shoji.actions.swapUp()spoon.Shoji.actions.swapDown()spoon.Shoji.actions.swapNext()spoon.Shoji.actions.swapPrev()spoon.Shoji.actions.swapMain()
-- Window statespoon.Shoji.actions.toggleFloat()
-- Layout actionsspoon.Shoji.actions.cycleLayout()spoon.Shoji.actions.setLayout("bsp")spoon.Shoji.actions.retileSpace()
-- Adjustment actionsspoon.Shoji.actions.resizeMainInc()spoon.Shoji.actions.resizeMainDec()spoon.Shoji.actions.incNmaster()spoon.Shoji.actions.decNmaster()