Configuration reference

All configuration options with types, defaults, and examples.

Usage

Pass options to configure() before calling start():

spoon.Shoji:configure({
  gap_outer = 16,
  default_layout = "bsp",
})
spoon.Shoji:start()

Options can also be changed after Shoji starts. Call retile() to apply:

spoon.Shoji:configure({ gap_inner = 12 })
spoon.Shoji:retile()

Layout options

default_layout

Layout assigned to new macOS Spaces.

Property	Value
Type	`string`
Default	`"tall"`

Must be a layout name present in enabled_layouts.

default_layout = "bsp"

enabled_layouts

Layouts available when cycling with cycle_layout action.

Property	Value
Type	`string[]`
Default	`{ "tall", "wide", "fullscreen", "bsp" }`
Min length	1

Available built-in layouts: tall, wide, fullscreen, bsp, grid, column, floating.

enabled_layouts = { "tall", "wide", "bsp", "grid" }

main_ratio

Ratio of the main area. Applies to layouts with a main/secondary split.

Property	Value
Type	`number`
Default	`0.5`
Range	`0.1` to `0.9`

At 0.5, main and secondary areas split equally. Higher values give more space to the main area.

main_ratio = 0.6

nmaster

Number of windows in the main area.

Property	Value
Type	`number`
Default	`1`
Min	`1`

nmaster = 2

Gap options

gap_outer

Space between windows and screen edges.

Property	Value
Type	`number`
Default	`0`
Unit	pixels
Min	`0`

gap_outer = 16

gap_inner

Space between adjacent windows.

Property	Value
Type	`number`
Default	`0`
Unit	pixels
Min	`0`

gap_inner = 4

Filtering options

filter_mode

How filter_apps is interpreted.

Property	Value
Type	`string`
Default	`"blocklist"`
Values	`"blocklist"`, `"allowlist"`

"blocklist": tile all windows except apps in filter_apps
"allowlist": tile only apps in filter_apps (requires non-empty list)

filter_mode = "blocklist"

filter_apps

App bundle IDs affected by filter_mode.

Property	Value
Type	`string[]`
Default	`{}`

To find an app’s bundle ID: hs.application.frontmostApplication():bundleID()

filter_apps = {
  "com.apple.finder",
  "com.apple.Preview",
  "com.apple.systempreferences",
}

min_width

Minimum window width for tiling. Windows narrower than this are excluded.

Property	Value
Type	`number`
Default	`0` (disabled)
Unit	pixels
Min	`0`

min_width = 400

min_height

Minimum window height for tiling. Windows shorter than this are excluded.

Property	Value
Type	`number`
Default	`0` (disabled)
Unit	pixels
Min	`0`

min_height = 300

Alert options

show_layout_alerts

Display on-screen alerts when the layout changes.

Property	Value
Type	`boolean`
Default	`true`

show_layout_alerts = false

show_layout_icon

Display layout icon in on-screen alerts.

Property	Value
Type	`boolean`
Default	`true`

Only applies when show_layout_alerts is true.

show_layout_icon = false

alert_duration

How long layout alerts remain visible.

Property	Value
Type	`number`
Default	`0.5`
Unit	seconds
Min	`0`

alert_duration = 1.0

Drag-swap options

Reorder windows by dragging them over each other.

drag_swap

Enable drag-to-swap window reordering.

Property	Value
Type	`boolean`
Default	`false`

drag_swap = true

drag_min_distance

Minimum drag distance before a swap triggers.

Property	Value
Type	`number`
Default	`40`
Unit	pixels
Min	`0`

Lower values make swaps trigger more easily.

drag_min_distance = 30

drag_swap_sensitivity

How soon a swap triggers when entering another window’s area.

Property	Value
Type	`number`
Default	`0`
Range	`0` to `1`

At 0, the dragged window must reach the target’s center. Higher values trigger swaps sooner.

drag_swap_sensitivity = 0.3

drag_enabled_layouts

Layouts where drag-swap is active.

Property	Value
Type	`string[]`
Default	`{ "tall" }`

Cannot include "floating".

drag_enabled_layouts = { "tall", "wide", "bsp" }

Advanced options

strict_validation

Fail on invalid config instead of using defaults.

Property	Value
Type	`boolean`
Default	`true`

When false, invalid values are replaced with defaults and a warning is logged.

strict_validation = false

layouts

Custom layout implementations.

Property	Value
Type	`Layout[]`
Default	`nil`

See Custom layouts.

layouts = { require("my_custom_layout") }

hooks

Callbacks for lifecycle and window events.

Property	Value
Type	`table<HookType, function \| function[]>`
Default	`nil`

See Hooks reference for available hooks.

hooks = {
  after_tile = function(spaceID)
    print("Tiled space: " .. spaceID)
  end,
  layout_changed = function(spaceID, layout, prev)
    print("Layout: " .. (prev or "none") .. " -> " .. layout)
  end,
}

retile_on_focus

Retile when window focus changes.

Property	Value
Type	`boolean`
Default	`false`

Useful for magnifier-style layouts where the focused window gets more space.

retile_on_focus = true