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.
Command palette
spoon.Shoji:bindHotkeys({ open_command_palette = { { "ctrl", "alt" }, "/" },})Opens a searchable popup showing layouts and actions. Features:
- Search: Filter by name, description, or keybinding
- Layouts first: Icons, ✓ indicator for current layout
- Actions: Keybinding displayed as subtext (e.g., ⌃⌥F)
- Ordering: Layouts follow
enabled_layoutsorder
Press Return to select, Escape to cancel.
Cycle layout
spoon.Shoji:bindHotkeys({ cycle_layout_forward = { { "ctrl", "alt" }, "space" }, cycle_layout_backward = { { "ctrl", "alt", "shift" }, "space" },})Steps through enabled_layouts in order, wrapping
at the end. The backward action walks the list in
reverse.
spoon.Shoji:configure({ enabled_layouts = { "tall", "wide", "bsp", "monocle" },})-- Pressing cycle_layout_forward: tall -> wide -> bsp -> monocle -> ...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_monocle = { { "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 ││ │ ││ │ ││ │ ││ │ ││ │ ││ │ ││ │ ││ │ │└─────────────────────────────────────────┴─────────────────┘Main window count
Control how many windows share the main area:
spoon.Shoji:bindHotkeys({ increase_main_count = { { "ctrl", "alt" }, "," }, decrease_main_count = { { "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_main_count = true
Visual effect
Tall with main_count = 1:
┌─────────────────────────────┬─────────────────────────────┐│ │ ││ │ ││ │ ││ │ Win 2 ││ │ ││ │ ││ │ ││ ├─────────────────────────────┤│ Win 1 │ ││ │ ││ │ ││ │ ││ │ Win 3 ││ │ ││ │ ││ │ ││ │ │└─────────────────────────────┴─────────────────────────────┘Tall with main_count = 2:
┌─────────────────────────────┬─────────────────────────────┐│ │ ││ │ ││ │ ││ Win 1 │ Win 3 ││ │ ││ │ ││ │ ││ │ │├─────────────────────────────┼─────────────────────────────┤│ │ ││ │ ││ │ ││ Win 2 │ Win 4 ││ │ ││ │ ││ │ ││ │ │└─────────────────────────────┴─────────────────────────────┘Retile space
spoon.Shoji:bindHotkeys({ retile_space = { { "ctrl", "alt", "shift" }, "r" },})Reapplies the current layout using the existing parameters. Useful when:
- Windows look misaligned
- You manually moved windows and want the layout back
This does not reset main_ratio, main_count, or layout-specific state.
Reset space
reset_space = { { "ctrl", "alt", "shift" }, "0" }Resets layout parameters to defaults and retiles:
main_ratioreturns to the configured defaultmain_countreturns to the configured default- Layout-specific state clears (BSP split ratios, etc.)
Per-macOS Space persistence
Layout settings are tracked separately for each macOS Space:
- Current layout
- Main ratio
- Main window count
- Layout-specific state (e.g., BSP split ratios)
Switching macOS Spaces restores that macOS Space’s configuration automatically.