Layout control
Layout control actions switch between layouts and tweak layout parameters. This page focuses on behavior and examples. For the full action list and defaults, see Actions reference.
Cycle layout
spoon.Shoji:bindHotkeys({ cycle_layout = { { "ctrl", "alt" }, "space" },})Steps through enabled_layouts in order, wrapping at the end:
spoon.Shoji:configure({ enabled_layouts = { "tall", "wide", "bsp", "fullscreen" },})-- Pressing cycle_layout: tall -> wide -> bsp -> fullscreen -> tall -> ...An on-screen alert shows the new layout name.
Set layout directly
Switch to a specific layout without cycling:
spoon.Shoji:bindHotkeys({ set_layout_tall = { { "ctrl", "alt" }, "1" }, set_layout_wide = { { "ctrl", "alt" }, "2" }, set_layout_bsp = { { "ctrl", "alt" }, "3" }, set_layout_fullscreen = { { "ctrl", "alt" }, "4" },})Action names follow the pattern set_layout_<name>. Any registered layout
works, even those not in enabled_layouts.
Main ratio
Control how much screen space the main area occupies:
spoon.Shoji:bindHotkeys({ increase_main_ratio = { { "ctrl", "alt" }, "=" }, decrease_main_ratio = { { "ctrl", "alt" }, "-" },})Each press adjusts by 5%. The ratio stays within 10%-90%.
Supported layouts
- Tall and Wide
- Any custom or composed layout with
adjustable_ratio = true
Other layouts ignore these actions.
Visual effect
Tall at 50% ratio:
┌─────────────────────────────┬─────────────────────────────┐│ │ ││ │ ││ │ ││ │ ││ │ ││ │ ││ │ ││ │ ││ Main │ Stack ││ │ ││ │ ││ │ ││ │ ││ │ ││ │ ││ │ ││ │ │└─────────────────────────────┴─────────────────────────────┘Tall at 70% ratio:
┌─────────────────────────────────────────┬─────────────────┐│ │ ││ │ ││ │ ││ │ ││ │ ││ │ ││ │ ││ │ ││ Main │ Stack ││ │ ││ │ ││ │ ││ │ ││ │ ││ │ ││ │ ││ │ │└─────────────────────────────────────────┴─────────────────┘Master count (nmaster)
Control how many windows share the main area:
spoon.Shoji:bindHotkeys({ increase_nmaster = { { "ctrl", "alt" }, "," }, decrease_nmaster = { { "ctrl", "alt" }, "." },})The minimum is 1. The maximum equals the total window count (at which point the stack area disappears).
Supported layouts
- Tall and Wide
- Any custom or composed layout with
adjustable_nmaster = true
Visual effect
Tall with nmaster = 1:
┌─────────────────────────────┬─────────────────────────────┐│ │ ││ │ ││ │ ││ │ Win 2 ││ │ ││ │ ││ │ ││ Win 1 ├─────────────────────────────┤│ │ ││ │ ││ │ ││ │ Win 3 ││ │ ││ │ ││ │ ││ │ ││ │ │└─────────────────────────────┴─────────────────────────────┘Tall with nmaster = 2:
┌─────────────────────────────┬─────────────────────────────┐│ │ ││ │ ││ │ ││ Win 1 │ Win 3 ││ │ ││ │ ││ │ ││ │ │├─────────────────────────────┼─────────────────────────────┤│ │ ││ │ ││ │ ││ Win 2 │ Win 4 ││ │ ││ │ ││ │ ││ │ │└─────────────────────────────┴─────────────────────────────┘Retile space
spoon.Shoji:bindHotkeys({ retile_space = { { "ctrl", "alt", "shift" }, "r" },})Reapplies the layout and resets all parameters to their defaults. Useful when:
- Windows look misaligned
- Ratio or nmaster adjustments need undoing
- BSP split state needs a fresh start
Per-macOS Space persistence
Layout settings are tracked separately for each macOS Space:
- Current layout
- Main ratio
- Master count
- Layout-specific state (e.g., BSP split ratios)
Switching macOS Spaces restores that macOS Space’s configuration automatically.