Multi-Monitor Support

How It Works

• Independent per-display workspaces: Each monitor has its own workspace stack. When you switch workspaces on one display, it does not affect the others.
• Auto-detection: Displays are detected automatically. Hotplug is handled automatically.
• Focus follows mouse: The display under the mouse cursor is the target for the keyboard shortcuts.

Parked Window Thumbnails

When a column would extend more than 50% of its width onto an adjacent display (screen overlap), macOS would move the window to that display. To stop this, FazerWM shows a thumbnail. The thumbnail shows what would remain visible on the original display. FazerWM then parks the window offscreen:

• Window streaming: Real-time window content at a configurable FPS (Pro) or at 1 FPS (Free)
• Click-to-focus: Click a parked thumbnail to scroll that column into view
• Vertical slice rendering: Only the visible portion of the column is shown

Cross-Screen Drag

Drag windows between displays in normal mode and in overview mode:

• The thumbnail and column frames are registered for cross-screen hit testing
• The source screen and the destination screen are tracked independently

Display Hotplug

FazerWM remembers how your windows are arranged across displays, so plugging in or unplugging a monitor moves your windows intelligently instead of dumping them all on one screen.

Returning to a remembered setup

When you reconnect a set of displays you have used before in this session, every window goes back to the exact display and workspace it was on. Dock your laptop at the desk you used this morning and your windows snap back to where you left them.

Switching to a new setup

When a set of displays you have not used before connects, FazerWM places your windows by their role:

• Pro: Windows follow their role. Whatever was on your primary display lands on the new primary; whatever was on a side monitor lands on the side monitors. Windows that were together on one monitor stay together. When there are fewer side monitors than before, the extra groups merge onto the last one; when there are none, they fall back to the primary.
• Free: Every window is pulled onto the primary display. You can still spread them out, drag them to other monitors, and open new windows on any display afterwards. Multi-display use is free; this only affects that one transition moment.

Windows you moved yourself

A window you repositioned by hand is not snapped back to a stale remembered spot. On the next setup switch, Pro re-places it by its role (a side-monitor window lands on a side monitor again), and Free moves it to the primary. Once it settles onto a display and is re-remembered there, that setup's memory is fresh again.

Manually resized columns

A column whose width you set by hand (keyboard steps or an edge drag) keeps that width through display changes. Reconnect the same display and the width returns exactly. If a removed display's windows migrate to a surviving monitor with different dimensions, the column keeps the same proportion of the tiled area; a 75% column is still 75% there. The same applies when you move a column or window to another monitor yourself, by keyboard or by dragging: the width follows the window and lands at the same proportion on the new display. See Resizing.

Dock blips, sleep, and wake

Brief disconnects (a loose cable, a dock that drops for a second) and staggered wake-from-sleep, where displays come back one at a time over several seconds, are handled without thrash. FazerWM waits for the connected set to settle before moving anything, so a display arriving late does not trigger a partial reshuffle. Manually resized columns get their width back once the set has settled.

Rearranging displays

Moving monitors around in System Settings without unplugging anything keeps the connected set, and with it your arrangement memory, the same, so every window stays on the display and workspace it was on. While you drag the arrangement around, macOS sometimes re-anchors a window onto a different display; FazerWM notices and pulls it back to its remembered display. The overview is also rebuilt against the new geometry, so its overlays and drop zones track the moved screens.

Other hotplug details

• Window rules take precedence: a window pinned by a rule (to a named workspace or a preferred display) follows its rule on every setup.
• Named workspace configs are checked for display preferences.
• The SketchyBar bar height is read again, so the layout stays correct on all displays.

Display Focus

The cursor follows the focused or the moved window, per the pointerFollowsFocus setting (see Configuration). The setting can be the focused display, the focused window, or nowhere. This setting is a Pro feature. On the free tier, the cursor does not follow the focus. It applies to display focus, to move-to-monitor, and to cross-display wrap alike.

Move to Monitor

Move columns or windows to the adjacent displays. A manually resized column keeps its width, landing at the same proportion of the new display's tiled area:

Cross-Display Wrap Pro

When cross-display-wrap is enabled (the default for Pro), the focus and the window-move actions do not stop at the workspace edge. They continue onto the physically adjacent display. The displays themselves stay independent, each with its own workspaces and layout:

• Focus ←/→ at the last column jumps to the nearest window on the neighbor display
• Focus ↑/↓ at the top or bottom window jumps to the display above or below. It keeps your horizontal position.
• Move column ←/→ and merge window ←/→ move the column or the window onto the neighbor display. It becomes a new column.
• Reorder window ↑/↓ moves the window onto the display above or below

Per pointerFollowsFocus, the cursor follows the wrapped-to window. So repeated presses continue across each display in that direction (in display or window mode).

The wrap detent (crossDisplayWrapDetent, on by default) guards these edges; see Two-Press Detent below.

Toggle Wrap focus & moves across displays under Settings → General → Window Behavior. Or set it in the config file:

layout:
  crossDisplayWrap: true

Two-Press Detent

With cross-display-wrap-detent (default on), the first press toward an adjacent display only arms the crossing. Nothing visibly happens. The second press does the jump or the move. This guards against a single stray keypress that carries you onto another monitor. The detent applies only while wrap is on.

Toggle Require two presses to cross displays under Settings → General → Window Behavior. Or set it in the config file:

layout:
  crossDisplayWrapDetent: true