Window filtering

Control which applications and windows participate in tiling. This page explains filtering behavior and examples. For the complete list of configuration options, see Configuration overview.

Filter modes

Shoji supports two filtering strategies:

Mode	Behavior
blocklist (default)	Tile all apps except those in filter_apps
allowlist	Tile only apps in filter_apps

Blocklist mode

Exclude specific apps from tiling. Good for apps with non-standard windows (Finder, System Settings) or apps that should remain floating:

spoon.Shoji:configure({
  filter_mode = "blocklist",
  filter_apps = {
    "com.apple.finder",
    "com.apple.systempreferences",
    "com.apple.Preview",
    "com.1password.1password",
  },
})

No nil holes in arrays

Lua arrays stop at the first nil. A list like { "com.app.one", nil, "com.app.two" } silently drops the third entry. Ensure your filter_apps table has no gaps.

Excluded apps behave as floating windows that do not affect the tiled layout.

Allowlist mode

Tile only specific apps. Useful when working with a fixed set of apps and everything else should float:

spoon.Shoji:configure({
  filter_mode = "allowlist",
  filter_apps = {
    "com.apple.Terminal",
    "org.mozilla.firefox",
    "com.microsoft.VSCode",
  },
})

Caution

An empty allowlist tiles nothing. Shoji treats this as a configuration error. Always include at least one app when using allowlist mode.

Finding bundle IDs

Every macOS app has a unique bundle ID. The most reliable way is Terminal:

osascript -e 'id of app "Safari"'

Replace “Safari” with the app’s name.

Common bundle IDs

Application	Bundle ID
Finder	com.apple.finder
System Settings	com.apple.systempreferences
Preview	com.apple.Preview
Terminal	com.apple.Terminal
Safari	com.apple.Safari
Firefox	org.mozilla.firefox
VS Code	com.microsoft.VSCode
iTerm2	com.googlecode.iterm2
Slack	com.tinyspeck.slackmacgap
1Password	com.1password.1password

Minimum window size

Exclude small windows from tiling. Useful for filtering dialogs, popups, and utility windows:

spoon.Shoji:configure({
  min_width = 400,   -- Minimum width in pixels
  min_height = 300,  -- Minimum height in pixels
})

Windows smaller than these dimensions remain floating. Set to 0 to disable size filtering.

Tip

Minimum size filtering is a good way to exclude popups and dialogs without listing every app’s bundle ID. Start with 400×300 and adjust based on your workflow.

Per-window floating

Toggle individual windows to floating regardless of filter settings. Bind the action:

spoon.Shoji:bindHotkeys({
  toggle_float = { { "ctrl", "alt", "shift" }, "t" },
})

Floating windows:

• Do not participate in tiling calculations.
• Can be freely positioned and resized.
• Keep their floating state across retiles.
• Reset to tiled when closed and reopened.

Combining filters

Filters work together. A window must pass all of them to be tiled:

1. App must not be in blocklist (or must be in allowlist).
2. Window must meet minimum size requirements.
3. Window must not be manually set to floating.

spoon.Shoji:configure({
  filter_mode = "blocklist",
  filter_apps = { "com.apple.finder" },
  min_width = 400,
  min_height = 300,
})

With this configuration, Finder windows always float, and windows from other apps smaller than 400x300 also float.