Default keybindings

Shoji uses Ctrl+Alt as the primary modifier to avoid conflicts with macOS Option key special characters. Navigation follows Vim-style H/J/K/L for directional movement.

These keybindings are enabled automatically when you call spoon.Shoji:start(), so you can start using them right away.

Navigation

Move focus between windows.

• 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 previous: Ctrl+Alt+P
• Focus last (history): Ctrl+Alt+Tab

Windows

Swap window positions and toggle window state.

• 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 previous: Ctrl+Alt+Shift+P
• Swap main: Ctrl+Alt+Shift+Return
• Toggle floating: Ctrl+Alt+Shift+T
• Toggle zoom: Ctrl+Alt+F

Floating windows stay outside the tiling layout and can be moved freely. Zoom temporarily maximizes a window to fill the screen; press again to restore it.

Layout

Change how windows are arranged on screen.

• Cycle layout forward: Ctrl+Alt+Space
• Cycle layout backward: Ctrl+Alt+Shift+Space
• Increase main ratio: Ctrl+Alt+=
• Decrease main ratio: Ctrl+Alt+-
• Add main window: Ctrl+Alt+,
• Remove main window: Ctrl+Alt+.
• Retile space: Ctrl+Alt+Shift+R
• Reset space: Ctrl+Alt+Shift+0

Main ratio controls how much screen space the main area occupies (Tall and Wide layouts). main_count controls how many windows appear in the main area (Tall and Wide layouts).

Help

• Toggle cheatsheet: Ctrl+Alt+Shift+/
• Open command palette: Ctrl+Alt+/

The cheatsheet displays an overlay showing all keybindings. Press Escape or the same shortcut to dismiss.

The command palette opens a searchable picker to switch layouts and run actions.

BSP layout actions

These bindings only apply when using the BSP (binary space partitioning) layout.

• Shrink horizontal: Ctrl+Cmd+H
• Expand horizontal: Ctrl+Cmd+L
• Shrink vertical: Ctrl+Cmd+K
• Expand vertical: Ctrl+Cmd+J
• Rotate split: Ctrl+Cmd+R

Partition layout actions

These bindings only apply when using a Partition layout.

• Send to next region: Ctrl+Alt+]
• Send to previous region: Ctrl+Alt+[
• Balance regions: Ctrl+Alt+Shift+B

Binding presets

The default bindings use Ctrl+Alt to avoid conflicts with macOS Option key special characters. If you prefer different modifiers, here are some common presets you can adapt:

Non-US keyboard?

If you use a QWERTZ, AZERTY, or Nordic layout, the default Ctrl+Alt modifier may conflict with special character input. See the Non-QWERTY keyboards recipe for complete presets that avoid these conflicts.

macOS-style (Cmd+Alt)

Feels more native to macOS users:

local mods = { "cmd", "alt" }
local modsShift = { "cmd", "alt", "shift" }

spoon.Shoji:bindHotkeys({
  focus_left = { mods, "h" },
  focus_right = { mods, "l" },
  focus_up = { mods, "k" },
  focus_down = { mods, "j" },
  swap_left = { modsShift, "h" },
  swap_right = { modsShift, "l" },
  swap_up = { modsShift, "k" },
  swap_down = { modsShift, "j" },
  cycle_layout_forward = { mods, "space" },
})

Hyper key (Ctrl+Alt+Cmd+Shift)

For Karabiner-Elements users who map Caps Lock to Hyper:

local hyper = { "ctrl", "alt", "cmd", "shift" }

spoon.Shoji:bindHotkeys({
  focus_left = { hyper, "h" },
  focus_right = { hyper, "l" },
  focus_up = { hyper, "k" },
  focus_down = { hyper, "j" },
  swap_left = { hyper, "left" },
  swap_right = { hyper, "right" },
  swap_up = { hyper, "up" },
  swap_down = { hyper, "down" },
  cycle_layout_forward = { hyper, "space" },
})

Custom keybindings

Calling bindHotkeys() merges your bindings with defaults. Your bindings override defaults for the same action:

-- Only override specific bindings; others use defaults
spoon.Shoji:bindHotkeys({
  focus_left = { { "cmd", "alt" }, "h" },  -- Override
  focus_right = { { "cmd", "alt" }, "l" }, -- Override
  -- All other actions use default bindings
})

Tip

You don’t need to redefine all bindings when customizing. Just specify the actions you want to change—the rest keep their defaults.

To disable a specific binding, set it to an empty table:

spoon.Shoji:bindHotkeys({
  focus_right = {},  -- Disabled (no keybinding)
})

Disabled actions are hidden from the cheatsheet.

Hotkey format

Shoji accepts two formats for specifying hotkeys:

-- Standard Spoon format (modifiers as nested table)
{ { "ctrl", "alt" }, "h" }

-- Flat format (modifiers and key in single table)
{ "ctrl", "alt", "h" }

Available modifiers: ctrl, alt, cmd, shift, fn.

Cheatsheet configuration

Customize the keybinding cheatsheet appearance:

spoon.Shoji:configure({
  cheatsheet_style = "system",  -- "light", "dark", or "system" (default)
})

The cheatsheet can be dismissed by pressing Escape or the same toggle shortcut (Ctrl+Alt+Shift+/). The cheatsheet only shows actions that have keybindings assigned.