Multi-Monitor Guide and Status

[BarutSRB]

Multi-Monitor Usage Guide

Multi-monitor support is available but still evolving. This guide explains how to use it correctly in its current state and outlines known limitations.

Current Capabilities

• Multiple monitors are supported with independent workspace assignments.
• Each workspace is rendered on exactly one monitor.
• Different workspaces can use different layouts.
• Workspaces do not need to be persistent.
• You can move windows between different monitor's workspaces

Required Monitor Arrangement

• Monitors must be arranged exactly as shown in the reference layout.
• The leftmost monitor must be configured as the top (main) monitor.
• This configuration is required for correct focus, workspace traversal, and mouse movement.

Workspace Assignment Rules

• You must explicitly:

  1. Assign a layout to a workspace
  2. Bind that workspace to a specific monitor

• A workspace cannot be shown on two monitors at the same time.

Mouse Configuration (Strongly Recommended)

• Enable mouse wrap.
• This allows the cursor to move naturally left-to-right across monitors.
• Without mouse wrap, cross-monitor navigation will feel weird due to how the arrangment of monitors is required within macOS system settings.

Known Limitations

• Some multi-monitor commands are only partially wired.
• Certain commands may be removed or merged in future releases to reduce complexity.
• Monitor-specific behaviors may change as the command model is simplified.

Multi-monitor support should currently be considered usable but not finalized. Expect breaking changes as the model is refined.

[yougotwill]

For anyone struggling with multi-monitor, I had to do the following to get multi-monitor niri support working.

NOTE: I'm on macOS Sequoia and not sure if things work as they should on Tahoe.

1. I had to move the secondary monitor slightly to the right. See below

2. Mouse warp only worked after I swapped the monitors in the mouse warp section on the settings page. I swapped the secondary monitor to be the main and it started working in the inverse direction. When I swapped them once again so the correct monitor is the main monitor then it works as expected.

Update:

Once I did the above, I changed the display arrangement back to the recommended layout and things are working as expected uninstall I restarted OmniWM and it stopped working again. Seems like a bug. For now I will keep my tweaked display arrangement.

[yougotwill]

For anyone struggling with multi-monitor, I had to do the following to get multi-monitor niri support working.

NOTE: I'm on macOS Sequoia and not sure if things work as they should on Tahoe.

1. I had to move the secondary monitor slightly to the right. See below

2. Mouse warp only worked after I swapped the monitors in the mouse warp section on the settings page. I swapped the secondary monitor to be the main and it started working in the inverse direction. When I swapped them once again so the correct monitor is the main monitor then it works as expected.

Update:

Once I did the above, I changed the display arrangement back to the recommended layout and things are working as expected uninstall I restarted OmniWM and it stopped working again. I can't seem to make it once work again after my first attempt. But maybe the above info will be helpful for fixing the issues 🥲🙏

[BarutSRB]

@yougotwill Here is how I have it setup and it works fine with still some sporadic hiccups, I'm in the process of rewritting some stuff in Zig and am already seeing it being better, once done I'll focus on multi-monitor support, for now it works for me with occasionally me needing to either press alt+shift+b or switch back and forth once or twice between workspaces on different monitors to refresh and retile it properly.

1. Displays have seperate spaces must be off.

2. I put the larger resolution monitor on top and made it main due to the macos status bar.

3. That larger monitor is the VG27A

4. I also am using only Niri layout for my workspaces as dwindle is still very buggy

[yougotwill]

Okay so I have got multi-monitor to work. A couple of points.

1. I reverted to my original settings file and mouse warp worked as expected. See here settings.json
2. Using your recommended desktop arrangement, I was using focus/move left and right instead of up and down which is why I thought it was broken. Works perfectly now that I am using up and down.
3. If I move a window between monitors (workspace 1 to workspace 2) with the mouse it doesn't tile and if I make a new window on workspace 2 then both windows are moved back to workspace 1 on their own. However if I use the keyboard shortcuts to move a window to workspace 2 and then focus on workspace 2 and then if I create a new window they tile correctly. So I think you might need logic to detect when a window has been moved between monitors and then focus on that workspace and that window? Note: Focus follows mouse is turned off for this.
4. It would be useful to be able to change focus between monitors even if there are no open windows. That why I can make new windows (say Finder for example) on a separate monitor.
5. When you turn on "Mouse to Focused" it does not move reliably between monitors when moving windows or focusing them.
6. It might be useful to have additional shortcuts for moving the mouse between monitors if you don't want it to be linked with changing window focus between monitors.

That's all the feedback I have for now. I hope it's useful. Thanks again for taking the time 🙏

[BarutSRB]

Great feedback, thank you ❤️ for now you can only swap or insert windows with mouse by holding alt or alt+shift (shows a blue overlay of where that window will go, moving a window manually with a mouse to another screen isn't implemented, currently, like you said, only via hotkeys.

[ethaneng]

@BarutSRB any plans to support 2 monitors physically stacked vertically? I'll often connect to an external monitor and have my laptop open beneath it like so:

 +---------------------+
|                     |
|   EXTERNAL MONITOR  |
|                     |
|                     |
|                     |
|                     |
+---------------------+
|                     |
|   LAPTOP DISPLAY    |
|                     |
|                     |
|                     |
|                     |
+----------+----------+

Seems like the current support only works when physically placed left/right of eachother.

[BarutSRB]

@ethaneng It works even when you stack monitors liek you showed, but the mouse warp prevents you from using the cursor to traverse the monitors up/down. Open a feat request and I can do it at a later point after I finish fixing some other bugs.

[ethaneng]

@ethaneng It works even when you stack monitors liek you showed, but the mouse warp prevents you from using the cursor to traverse the monitors up/down. Open a feat request and I can do it at a later point after I finish fixing some other bugs.

Awesome. Just opened: #129

[santip]

Hey @BarutSRB, first of all great work, this looks awesome and from the looks of it you're making progress at a remarkable speed, thank you for all your hard work.

Rergarding multimonitor support, it sounds like it's currently limited to a fixed workspace->monitor mapping. In my current aerospace setup, I use workspaces mostly in a project/function oriented fashion and I swtich between single, double and triple monitor setups throughout the day. In aerospace I heavily rely on move-workspace-to-monitor and summon-workspace commands to arrange my workspaces across my screens depending on what I'm doing.

Do you think it would be possible to adapt OmniWM to support shuffling workspaces aronud across displays?