v5-compositor-settings-niri.md
Add the following settings to your Niri configuration file (usually located at ~/.config/niri/config.kdl).
Section titled “Autostart Noctalia”
spawn-at-startup "noctalia"
Section titled “Compositor Settings”
These settings are for general window appearance and functionality.
window-rule { // Rounded corners for a modern look. geometry-corner-radius 20
// Clips window contents to the rounded corner boundaries. clip-to-geometry true}
// Floating Noctalia settings window.window-rule { match app-id="dev.noctalia.Noctalia" open-floating true default-column-width { fixed 1080; } default-window-height { fixed 920; }}
debug { // Allows notification actions and window activation from Noctalia. honor-xdg-activation-with-invalid-serial}
Both spawn-sh and spawn are usable to run Noctalia keybinds.
Add these binds to your ~/.config/niri/config.kdl:
binds { // Core Noctalia binds Mod+Space { spawn-sh "noctalia msg panel-toggle launcher"; } Mod+S { spawn-sh "noctalia msg panel-toggle control-center"; } Mod+Comma { spawn-sh "noctalia msg settings-toggle"; }
// Audio & Brightness XF86AudioRaiseVolume { spawn-sh "noctalia msg volume-up"; } XF86AudioLowerVolume { spawn-sh "noctalia msg volume-down"; } XF86AudioMute { spawn-sh "noctalia msg volume-mute"; } XF86MonBrightnessUp { spawn-sh "noctalia msg brightness-up"; } XF86MonBrightnessDown { spawn-sh "noctalia msg brightness-down"; }}
Section titled “Optional Type to Launch”
Noctalia can open its launcher when you start typing in niri’s overview. This is disabled by default because it requires a tiny keyboard-focus layer surface while overview is open, which means some niri overview-only keyboard state, such as the app focus ring, may not behave exactly like native overview navigation.
[shell]niri_overview_type_to_launch_enabled = true
You can also enable this from Settings → Niri → Overview.
Section titled “Wallpapers setup”
Next, choose one of the following options for your wallpaper and overview setup.
Section titled “Option 1: Blurred Overview Wallpaper”
This configuration places Noctalia’s dedicated backdrop layer (a blurred and tinted copy of the wallpaper) within Niri’s overview backdrop.
Blurred Overview Wallpaper
layer-rule { match namespace="^noctalia-backdrop" place-within-backdrop true}
Section titled “Option 2: Stationary Wallpaper”
If you prefer a stationary wallpaper that is visible at all times and does not scroll when switching workspaces, use the following configuration.
Stationary Wallpaper
// Place the regular wallpaper on the backdrop.layer-rule { match namespace="^noctalia-wallpaper" place-within-backdrop true}
// Set transparent workspace background color so the backdrop is visible at all times.layout { background-color "transparent"}
// Optionally, disable workspace shadows in the overview.overview { workspace-shadow { off }}
Section titled “Option 3: Flat Colored Overview”
If you prefer a more productivity-oriented look, use this minimal configuration.
Flat colored overview
overview { // Choose your favorite color. backdrop-color "#26233a"}
You can enable blur behind windows and Noctalia’s bar, panels, dock, and notifications.
/* Apps: blur them all without xray so it looks more realistic. */window-rule { background-effect { blur true xray false }}
/* Noctalia Disable xray on all our surfaces so it looks more realistic. Noctalia publishes blur regions automatically when ext-background-effects is available.*/layer-rule { match namespace="^noctalia-(bar-[^\"]+|notification|dock|panel|attached-panel|osd)$" background-effect { xray false // blur false }}
/* You can also fine-tune the blur effect globally. */blur { passes 2 // more passes = stronger blur (default: 3) offset 3.0 // sample distance per pass (default: 3.0) noise 0.03 // grain overlay (default: 0.02) saturation 1.0 // color saturation boost (default: 1.5)}
Section titled “Per-widget desktop layer rules”
Each desktop widget lives on its own layer-shell surface with a unique namespace, so you can target an individual widget with a layer-rule. The namespace is:
noctalia-desktop-widget-<type>-<id>
where <type> is the widget kind (clock, weather, sysmon, …) and <id> is the widget’s stable id. Run niri msg layers to list all layer surfaces and see the exact namespaces on your setup:
Bottom layer: Surface: Namespace: "noctalia-desktop-widget-clock-000000000000000a" Surface: Namespace: "noctalia-desktop-widget-weather-000000000000000b"
Match on ^noctalia-desktop-widget- to target every desktop widget at once, or narrow the pattern by type or full id for a single widget. For example, to match just the weather widget:
layer-rule { match namespace="^noctalia-desktop-widget-weather-"}