Configuration overview

You will learn

How to set gaps between windows
How to choose and enable layouts
How to exclude apps from tiling
How validation catches configuration errors

Shoji uses a single configure method that accepts a table of options. All options have sensible defaults, so you can start simple and add configuration as you discover what works for your workflow.

This page is the single source of truth for all options. The linked pages provide examples and rationale, not additional settings.

At a glance

Defaults favor no gaps and the tall layout
main_ratio range: 0.1 to 0.9; nmaster minimum: 1
strict_validation is true and rejects invalid values
Use the tables below for every available option

Basic setup

hs.loadSpoon("Shoji")

spoon.Shoji:configure({
  gap_outer = 0,
  gap_inner = 0,
  default_layout = "tall",
  enabled_layouts = { "tall", "wide", "fullscreen", "bsp" },
})

spoon.Shoji:start()

Configuration reference

The tables below list every available option. Links after each section point to examples and rationale.

Spacing

Option	Type	Default	Description
`gap_outer`	`number`	`0`	Gap around screen edges (pixels)
`gap_inner`	`number`	`0`	Gap between windows (pixels)

For examples and visual diagrams, see Gaps.

Layouts

Option	Type	Default	Description
`default_layout`	`string`	`"tall"`	Layout for new macOS Spaces
`enabled_layouts`	`string[]`	`tall, wide, fullscreen, bsp`	Layouts in cycle order
`main_ratio`	`number`	`0.5`	Main area ratio (0.1-0.9)
`nmaster`	`number`	`1`	Number of master windows
`layouts`	`Layout[]`	`nil`	Custom layouts to register
`retile_on_focus`	`boolean`	`false`	Retile when focus changes

Default enabled layouts: {"tall", "wide", "fullscreen", "bsp"}.

For layout examples and guidance, see Layouts.

Window filtering

Option	Type	Default	Description
`filter_mode`	`string`	`"blocklist"`	`"blocklist"` or `"allowlist"`
`filter_apps`	`string[]`	`{}`	App bundle IDs to filter
`min_width`	`number`	`0`	Minimum window width to tile
`min_height`	`number`	`0`	Minimum window height to tile

For filtering examples and bundle ID guidance, see Window filtering.

Alerts

Option	Type	Default	Description
`show_layout_alerts`	`boolean`	`true`	Show alerts on layout change
`show_layout_icon`	`boolean`	`true`	Show layout icon in alerts
`alert_duration`	`number`	`0.5`	Alert duration (seconds)

For alert behavior and customization examples, see Alerts.

Cheatsheet

Option	Type	Default	Description
`cheatsheet_style`	`string`	`"system"`	`"light"`, `"dark"`, or `"system"`
`cheatsheet_opacity`	`number`	`1.0`	Background opacity (0.1-1.0)
`cheatsheet_font`	`string`	`"Menlo"`	Font for shortcut keys
`cheatsheet_show_unbound`	`boolean`	`true`	Show unbound actions

For cheatsheet usage and keybinding customization, see Default keybindings.

Drag-to-swap

Option	Type	Default	Description
`drag_swap`	`boolean`	`false`	Enable drag-to-swap
`drag_min_distance`	`number`	`40`	Minimum drag distance (pixels)
`drag_swap_sensitivity`	`number`	`0`	Swap sensitivity (0-1)
`drag_enabled_layouts`	`string[]`	`{"tall"}`	Drag-swap layouts

For drag-to-swap behavior and examples, see Drag-to-swap.

Hooks

Option	Type	Default	Description
`hooks`	`table`	`nil`	Event callbacks

For hook names and arguments, see Hooks reference.

Validation

Option	Type	Default	Description
`strict_validation`	`boolean`	`true`	Fail on invalid config

Validation

Shoji validates your configuration on startup to catch mistakes early. If something is wrong, you will see a clear error message:

spoon.Shoji:configure({
  gap_outer = -5,   -- Invalid: minimum is 0
  main_ratio = 1.5, -- Invalid: maximum is 0.9
})
-- Error: gap_outer: must be >= 0, got -5

Permissive validation

Set strict_validation = false to fall back to defaults instead of failing:

spoon.Shoji:configure({
  strict_validation = false,
  gap_outer = -5,  -- Falls back to 0
})

Unknown keys

Shoji also warns about typos and unknown keys, which helps catch common mistakes:

spoon.Shoji:configure({
  gap = 10,  -- Typo: should be gap_outer or gap_inner
})
-- Warning: Unknown config key(s): 'gap'. Valid keys: ...