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

Section titled “Defaults”
  • gap_outer: 0
  • gap_inner: 0

When to use

Section titled “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

Section titled “Gap types”
┌───────────────────────────────────────────────────────────┐
│                                                           │
│                                                           │
│                                                           │
│  ┌──────────────────────┐       ┌──────────────────────┐  │
│  │                      │       │                      │  │
│  │                      │       │                      │  │
│  │                      │       │                      │  │
│  │                      │       │                      │  │
│  │          1           │       │          2           │  │
│  │                      │       │                      │  │
│  │                      │       │                      │  │
│  │                      │       │                      │  │
│  │                      │       │                      │  │
│  └──────────────────────┘       └──────────────────────┘  │
│                                                           │
│                                                           │
│                                                           │
└───────────────────────────────────────────────────────────┘
  • gap_outer: Space between windows and screen edges (all four sides)
  • gap_inner: Space between adjacent windows

Configuration

Section titled “Configuration”
spoon.Shoji:configure({
  gap_outer = 0,   -- Default: 0 pixels
  gap_inner = 0,   -- Default: 0 pixels
})

Things to know

Section titled “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

Section titled “Examples”

No gaps (edge-to-edge windows)

Section titled “No gaps (edge-to-edge windows)”
spoon.Shoji:configure({
  gap_outer = 0,
  gap_inner = 0,
})

Framed look (large outer, tight inner)

Section titled “Framed look (large outer, tight inner)”

Groups windows together with generous screen margins:

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

Spacious layout

Section titled “Spacious layout”

Visual separation between all windows:

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

Per-layout gaps

Section titled “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

Section titled “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

Section titled “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