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
Section titled “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
Section titled “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
Section titled “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
Section titled “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
Section titled “Supported layouts”- Tall and Wide
- Any custom or composed layout with
adjustable_ratio = true
Other layouts ignore these actions.
Visual effect
Section titled “Visual effect”Tall at 50% ratio:
┌─────────────────────────────┬─────────────────────────────┐│ │ ││ │ ││ │ ││ │ ││ │ ││ │ ││ │ ││ │ ││ Main │ Stack ││ │ ││ │ ││ │ ││ │ ││ │ ││ │ ││ │ ││ │ │└─────────────────────────────┴─────────────────────────────┘Tall at 70% ratio:
┌─────────────────────────────────────────┬─────────────────┐│ │ ││ │ ││ │ ││ │ ││ │ ││ │ ││ │ ││ │ ││ Main │ Stack ││ │ ││ │ ││ │ ││ │ ││ │ ││ │ ││ │ ││ │ │└─────────────────────────────────────────┴─────────────────┘Main window count
Section titled “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
Section titled “Supported layouts”- Tall and Wide
- Any custom or composed layout with
adjustable_main_count = true
Visual effect
Section titled “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
Section titled “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
Section titled “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
Section titled “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.