Niri

Add the following settings to your Niri configuration file (usually located at ~/.config/niri/config.kdl).

Autostart Noctalia

spawn-at-startup "noctalia"

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
}

IPC Keybinds

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"; }
    Alt+Tab { spawn-sh "noctalia msg window-switcher"; }
    // Niri has a built-in window switcher you might want to try it to see which one you prefer.

    // 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"; }
}

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.

Wallpapers setup

Next, choose one of the following options for your wallpaper and overview setup.

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.

layer-rule {
  match namespace="^noctalia-backdrop"
  place-within-backdrop true
}

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.

// 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
  }
}

Option 3: Flat Colored Overview

If you prefer a more productivity-oriented look, use this minimal configuration.

overview {
  // Choose your favorite color.
  backdrop-color "#26233a"
}

Blur

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
  }
}

/* Enable blur on noctalia's window switcher and disable xray. */
layer-rule {
    match namespace="noctalia-window-switcher"
    background-effect {
        blur true
        xray 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)
}

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-"
}

Laptop

To lock the screen when you close your laptop lid, add this to your Niri config file:

switch-events {
    lid-close { spawn "noctalia" "msg" "session" "lock-and-suspend"; }
}

You may also need to edit your logind.conf to set:

HandleLidSwitch=ignore
HandleLidSwitchExternalPower=ignore