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", "shift" }, "return" },
})

Both formats are supported:

-- Standard Spoon format (recommended)
focus_left = { { "ctrl", "alt" }, "h" }

-- Flat format
focus_left = { "ctrl", "alt", "h" }

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_last

Focus the previously focused window (history-based).

focus_last = { { "ctrl", "alt" }, "tab" }

Window management actions

Swap windows, toggle floating, or zoom.

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", "shift" }, "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" }

toggle_zoom

Temporarily float and maximize the focused window to fill the screen. Press again to restore the window to its tiled position. If the window was already floating before zooming, it stays floating when unzoomed.

toggle_zoom = { { "ctrl", "alt" }, "f" }

reset_window_order

Reset the window order for the current space back to the default (based on window creation time). No default hotkey.

UI actions

Open overlays and pickers.

toggle_cheatsheet

Toggle the keybinding cheatsheet overlay. Press again or Escape to dismiss.

toggle_cheatsheet = { { "ctrl", "alt", "shift" }, "/" }

open_command_palette

Open a searchable command palette. Displays all enabled layouts followed by executable actions. Layouts appear in enabled_layouts order. Search matches names, descriptions, and keybindings.

open_command_palette = { { "ctrl", "alt" }, "/" }

Navigation and directional swap actions (e.g., focus_left, swap_up) are excluded because they are typically bound to muscle-memory hotkeys.

Layout control actions

Change layouts and adjust layout parameters.

cycle_layout_forward

Cycle to the next layout in enabled_layouts.

cycle_layout_forward = { { "ctrl", "alt" }, "space" }

cycle_layout_backward

Cycle to the previous layout in enabled_layouts.

cycle_layout_backward = { { "ctrl", "alt", "shift" }, "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_main_count

Increase the number of main windows by 1.

increase_main_count = { { "ctrl", "alt" }, "," }

decrease_main_count

Decrease the number of main windows by 1 (minimum 1).

decrease_main_count = { { "ctrl", "alt" }, "." }

retile_space

Retile the current space with current parameters.

retile_space = { { "ctrl", "alt", "shift" }, "r" }

reset_space

Reset layout parameters (ratio, main_count) to defaults and retile.

reset_space = { { "ctrl", "alt", "shift" }, "0" }

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.

No default hotkeys are bound. To enable direct layout switching, add bindings manually:

spoon.Shoji:bindHotkeys({
  set_layout_tall = { { "ctrl", "alt" }, "1" },
  set_layout_wide = { { "ctrl", "alt" }, "2" },
  set_layout_bsp = { { "ctrl", "alt" }, "3" },
  set_layout_monocle = { { "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" }

Partition layout actions

These actions only take effect when a Partition layout is active.

send_to_next_region

Move the focused window to the next region (wraps around).

send_to_next_region = { { "ctrl", "alt" }, "]" }

send_to_prev_region

Move the focused window to the previous region (wraps around).

send_to_prev_region = { { "ctrl", "alt" }, "[" }

balance_regions

Reset region assignments to their declared count values.

balance_regions = { { "ctrl", "alt", "shift" }, "b" }

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+H
focus_right: Ctrl+Alt+L
focus_up: Ctrl+Alt+K
focus_down: Ctrl+Alt+J
focus_next: Ctrl+Alt+N
focus_prev: Ctrl+Alt+P
focus_last: Ctrl+Alt+Tab
swap_left: Ctrl+Alt+Shift+H
swap_right: Ctrl+Alt+Shift+L
swap_up: Ctrl+Alt+Shift+K
swap_down: Ctrl+Alt+Shift+J
swap_next: Ctrl+Alt+Shift+N
swap_prev: Ctrl+Alt+Shift+P
swap_main: Ctrl+Alt+Shift+Return
toggle_float: Ctrl+Alt+Shift+T
toggle_zoom: Ctrl+Alt+F
toggle_cheatsheet: Ctrl+Alt+Shift+/
open_command_palette: Ctrl+Alt+/
cycle_layout_forward: Ctrl+Alt+Space
cycle_layout_backward: Ctrl+Alt+Shift+Space
increase_main_ratio: Ctrl+Alt+=
decrease_main_ratio: Ctrl+Alt+-
increase_main_count: Ctrl+Alt+,
decrease_main_count: Ctrl+Alt+.
retile_space: Ctrl+Alt+Shift+R
reset_space: Ctrl+Alt+Shift+0
bsp_shrink_horizontal: Ctrl+Cmd+H
bsp_expand_horizontal: Ctrl+Cmd+L
bsp_shrink_vertical: Ctrl+Cmd+K
bsp_expand_vertical: Ctrl+Cmd+J
bsp_rotate: Ctrl+Cmd+R
send_to_next_region: Ctrl+Alt+]
send_to_prev_region: Ctrl+Alt+[
balance_regions: Ctrl+Alt+Shift+B

Calling actions directly

Call actions from Lua without hotkeys:

-- Focus actions
spoon.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.focusLast()  -- History-based

-- Swap actions
spoon.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 state
spoon.Shoji.actions.toggleFloat()
spoon.Shoji.actions.toggleZoom()

-- Layout actions
spoon.Shoji.actions.cycleLayoutForward()
spoon.Shoji.actions.cycleLayoutBackward()
spoon.Shoji.actions.openCommandPalette()  -- Opens command palette
spoon.Shoji.actions.setLayout("bsp")
spoon.Shoji.actions.retileSpace()

-- Adjustment actions
spoon.Shoji.actions.resizeMainInc()
spoon.Shoji.actions.resizeMainDec()
spoon.Shoji.actions.incMainCount()
spoon.Shoji.actions.decMainCount()