Niri config on macOS: your config.kdl, translated

How configuration differs

niri reads a single KDL file, ~/.config/niri/config.kdl, and live-reloads it. Because niri is the whole compositor, that file covers everything: input devices, monitors, layout, window rules, animations, startup programs and every key bind.

On macOS, a window manager is one app among many. Keyboards, trackpads, displays and login items are configured in System Settings, and the window manager configures only the layout. In ChainYourMac every option is in a settings window and applies the moment you change it. The same options are saved to a TOML file, ~/.paneru, that you can keep in your dotfiles if you like. Nothing here requires editing it.

The layout block, option by option

niri's defaults below come from its default-config.kdl (main branch, checked 6 October 2026). ChainYourMac's come from version 2.1.

Input: mouse, focus and trackpad

Window rules

niri's window-rule matches on app-id and title regexes, then sets things like open-floating, default widths, opacity or corner radius. ChainYourMac's rules match a bundle ID (macOS's version of an app ID) and/or a title regex, and can make a window float or give it a fixed slot on the strip. You usually create them with an app picker in the settings window. In the file, they look like this:

[windows.pip]
title = "Picture.*(in)?.*[Pp]icture"
floating = true

[windows.settings]
title = ".*"
bundle_id = "com.apple.systempreferences"
floating = true

Small fixed-size windows like Calculator and ChainYourMac's own settings already float automatically, so you need fewer rules than in niri. Visual rules such as opacity, corner radius and block-out-from have no equivalent, because on macOS Apple's WindowServer draws the windows.

Outputs and workspaces

niri's output "eDP-1" { … } blocks set mode, scale, position and transform. On a Mac that's System Settings → Displays. ChainYourMac adds one per-display option: Configuration → Displays can switch it off for a single display (saved as ignored_displays) and leave that screen's windows alone. As in niri, every managed display has its own strip.

niri's dynamic vertical workspaces and named workspaces have no direct counterpart. ChainYourMac uses macOS Spaces, and each Space gets its own strip. Use Mission Control to add Spaces, and System Settings → Keyboard → Keyboard Shortcuts → Mission Control for "Switch to Desktop N" keys.

Animations

niri's animations { } block can slow everything down, tune springs per animation, or load custom shaders. ChainYourMac has one spring for strip motion, synced to your display's refresh rate:

• animation_duration_ms (default 500): the spring's perceived duration. 0 turns animation off, like niri's off.
• animation_damping (default 0.9): 1.0 settles with no overshoot, and lower values bounce.

Shaders, blur and open/close effects are compositor features, and no macOS window manager can add them.

Everything else in config.kdl

A niri-flavoured starting config

If you want ChainYourMac to behave like a stock niri install, set these in the settings window, or put them in ~/.paneru:

[options]
preset_column_widths = [0.33333, 0.5, 0.66667]   # niri's three presets
gap_inner = 16                                   # niri: gaps 16
gap_outer = 16
center_focused_column = "never"                  # or "on-overflow" / "always"
focus_follows_mouse = false
mouse_follows_focus = false
swipe_gesture_fingers = 4                        # 3 = niri's count, see /setup first
focus_border = true                              # closest thing to niri's focus-ring

Pair it with the default ⌃⌥ shortcuts, which already follow niri's layout, and the strip will feel familiar within a few minutes. If you're still deciding between Mac tools, see niri for macOS for every option, free ones included.

FAQ