Gaps

Gaps add spacing between windows and screen edges. Both default to 0 pixels. This page focuses on gap behavior and examples. For the complete list of configuration options, see Configuration overview.

Defaults

• gap_outer: 0
• gap_inner: 0

When to use

• Use larger gap_outer for a framed, focused look
• Use larger gap_inner for clearer separation between windows
• Use 0 for edge-to-edge tiling or maximum screen real estate

Gap types

┌───────────────────────────────────────────────────────────┐
│                                                           │
│                                                           │
│                                                           │
│  ┌──────────────────────┐       ┌──────────────────────┐  │
│  │                      │       │                      │  │
│  │                      │       │                      │  │
│  │                      │       │                      │  │
│  │                      │       │                      │  │
│  │          1           │       │          2           │  │
│  │                      │       │                      │  │
│  │                      │       │                      │  │
│  │                      │       │                      │  │
│  │                      │       │                      │  │
│  └──────────────────────┘       └──────────────────────┘  │
│                                                           │
│                                                           │
│                                                           │
└───────────────────────────────────────────────────────────┘

• gap_outer: Space between windows and screen edges (all four sides)
• gap_inner: Space between adjacent windows

Configuration

spoon.Shoji:configure({
  gap_outer = 0,   -- Default: 0 pixels
  gap_inner = 0,   -- Default: 0 pixels
})

Things to know

• gap_inner only applies when you have multiple windows, since there is nothing to separate with a single window
• Very large gaps can bump into macOS minimum window size limits
• Negative values are invalid and fail when strict_validation is true
• Per-layout gap modifiers add on top of the global gaps

Examples

No gaps (edge-to-edge windows)

spoon.Shoji:configure({
  gap_outer = 0,
  gap_inner = 0,
})

Framed look (large outer, tight inner)

Groups windows together with generous screen margins:

spoon.Shoji:configure({
  gap_outer = 32,
  gap_inner = 4,
})

Spacious layout

Visual separation between all windows:

spoon.Shoji:configure({
  gap_outer = 16,
  gap_inner = 16,
})

Per-layout gaps

You can override gaps for specific layouts using the Gaps modifier. This is covered in the Advanced section after you’re familiar with the layout system.

Troubleshooting

• Gaps not changing: retile the current macOS Space with spoon.Shoji.actions.retileSpace()
• Still unchanged: confirm configure() runs before start()
• Errors on launch: check the Hammerspoon console for validation warnings