Niri keybindings on Mac: every default bind, mapped

Where these binds come from

The niri column below is taken from niri's resources/default-config.kdl on the main branch (checked 6 October 2026; the latest release is v26.04). In niri, Mod is Super when it runs as your session and Alt when it runs nested. Your own config may differ, since niri binds are entirely user-defined.

The ChainYourMac column shows the defaults for new installs of 2.1. If you upgraded from 2.0 you keep your old shortcuts, and the Shortcuts page offers a one-click switch to this set. Every binding can be re-recorded, and one action can have several shortcuts. That's how both arrows and H/L work at the same time, just like niri.

Why ⌃⌥ instead of ⌘

On Linux, Super is mostly unused by apps, which is why niri can claim it. On a Mac, ⌘ is the app modifier. ⌘W closes, ⌘H hides, ⌘[ goes back, and the list goes on. Plain ⌥ types characters (⌥E, ⌥U) and ⌥←/→ jumps by word in every text field. Control+Option is the combination macOS and apps leave free, so it's the closest thing a Mac has to a "Super layer". If you use Karabiner-Elements or a Hyper key, you can record those combinations instead.

Navigation: focus and move

The pattern is easy to remember: niri adds Ctrl to move what Mod focuses, and ChainYourMac adds ⇧. You can also drag a window by its title bar onto another column to reorder, which is the Mac version of niri's Mod+drag.

Column width and height

The width presets themselves are configurable in both. niri's default list is 1/3, 1/2 and 2/3. ChainYourMac's is 25, 33, 50, 67 and 75%, and you can change it under "Preset Window Widths". For a niri-identical feel, set it to 33/50/67. See niri config on macOS.

Stacking, tabs and floating

niri combines "consume" and "expel" into one key that does whichever makes sense. ChainYourMac keeps them separate: plain ⌃⌥ with a bracket stacks, and adding ⇧ pops out. Inside a stack, ⌃⌥⇧↑/↓ reorders windows, just like niri's move-window-up/down.

Monitors

Like niri, every display has its own strip, and windows never spill onto the neighbour. Dragging a window onto another display also moves it into that display's strip.

Workspaces, overview and system keys

This is where the two worlds part. niri owns the whole session, so its config also binds workspaces, launching apps and quitting. On a Mac those belong to macOS:

Touchpad and mouse gestures

niri's wiki lists these touchpad gestures: three-finger horizontal swipes move the view, three-finger vertical swipes switch workspaces, and four-finger vertical swipes open the Overview. On a Mac, macOS already uses three-finger swipes (and often four) for Spaces and Mission Control, so ChainYourMac's strip swipe defaults to four fingers horizontally. The strip follows your fingers 1:1 and then glides to the nearest window. You can switch it to three fingers, and the in-app Mac Setup screen checks for clashing macOS settings (setup guide). For the mouse, niri's Mod+drag to move a window becomes dragging by the title bar onto another column.

Setting niri-style binds by hand

You never need to touch a file, since the shortcut recorder handles everything. But if you keep dotfiles, ChainYourMac's optional TOML config (~/.paneru) uses readable binding names:

[bindings]
window_focus_west  = ["ctrl + alt - leftarrow", "ctrl + alt - h"]
window_focus_east  = ["ctrl + alt - rightarrow", "ctrl + alt - l"]
window_swap_west   = ["ctrl + alt + shift - leftarrow", "ctrl + alt + shift - h"]
window_swap_east   = ["ctrl + alt + shift - rightarrow", "ctrl + alt + shift - l"]
window_resize      = "ctrl + alt - r"       # niri: switch-preset-column-width
window_fullwidth   = "ctrl + alt - f"       # niri: maximize-column
window_center      = "ctrl + alt - c"       # niri: center-column
window_tabbed      = "ctrl + alt + shift - t" # niri: toggle-column-tabbed-display
window_manage      = "ctrl + alt - t"       # niri: toggle-window-floating

Other names include window_focus_first/_last, window_swap_first/_last, window_wider, window_narrower, window_taller, window_shorter, window_equalize, window_stack, window_unstack, window_consume_east, window_expel_west and window_nextdisplay. For the layout options (widths, gaps, centering), continue to niri config on macOS.

FAQ