Skip to content
Shoji

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.

Partition region gaps

Partition has a built-in gap option that controls spacing between regions. This is separate from gap_inner/gap_outer — it only affects the boundaries between partition regions, not the windows within them.

Partition.horizontal({
  { ratio = 0.5, layout = Tall, count = 1 },
  { ratio = 0.5, layout = Column },
}, { gap = 20 })

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