Layer Rules

Configure behavior for individual layer-shell surfaces in niri

Available since version 25.01

Layer rules let you adjust behavior for individual layer-shell surfaces. They work similarly to window rules, with match and exclude directives that control which layer-shell surfaces the rule should apply to, and a number of properties that you can set.

Layer rules are processed and work very similarly to window rules, just with different matchers and properties. Please read the window rules documentation to learn how matching works.

Configuration Structure

Here’s an example showing all available matchers and properties:

layer-rule {
    match namespace="waybar"
    match at-startup=true

    // Properties that apply continuously.
    opacity 0.5
    block-out-from "screencast"
    // block-out-from "screen-capture"

    shadow {
        on
        // off
        softness 40
        spread 5
        offset x=0 y=5
        draw-behind-window true
        color "#00000064"
        // inactive-color "#00000064"
    }

    geometry-corner-radius 12
    place-within-backdrop true
    baba-is-float true
}

Layer Surface Matching

namespace

namespace · string (regex)

A regular expression that should match anywhere in the surface namespace. You can find the namespaces of all open layer-shell surfaces by running niri msg layers.

// Match surfaces with namespace containing "waybar"
layer-rule {
    match namespace="waybar"
}

You can read about the supported regular expression syntax in the Rust regex documentation.

at-startup

at-startup · boolean

Matches during the first 60 seconds after starting niri. Can be true or false.

// Show layer-shell surfaces with 0.5 opacity at niri startup, but not afterwards.
layer-rule {
    match at-startup=true
    opacity 0.5
}

Dynamic Properties

These properties apply continuously to open layer-shell surfaces.

block-out-from

block-out-from · string

Block out surfaces from xdg-desktop-portal screencasts or all screen captures. Surfaces will be replaced with solid black rectangles.

Options:

• "screencast" - Block from screencasts only
• "screen-capture" - Block from all screen captures

This can be useful for notifications. The same caveats and instructions apply as for the block-out-from window rule.

// Block out mako notifications from screencasts.
layer-rule {
    match namespace="^notifications$"
    block-out-from "screencast"
}

opacity

opacity · number

Set the opacity of the surface. 0.0 is fully transparent, 1.0 is fully opaque. This is applied on top of the surface’s own opacity, so semitransparent surfaces will become even more transparent.

Opacity is applied to every child of the layer-shell surface individually, so subsurfaces and pop-up menus will show window content behind them.

// Make fuzzel semitransparent.
layer-rule {
    match namespace="^launcher$"
    opacity 0.95
}

shadow

Available since version 25.02

shadow · object

Override the shadow options for the surface. These rules have the same options as the normal shadow config in the layout section.

Unlike window shadows, layer surface shadows always need to be enabled with a layer rule. That is, enabling shadows in the layout config section won’t automatically enable them for layer surfaces.

Layer surfaces have no way to tell niri about their visual geometry. For example, if a layer surface includes some invisible margins (like mako), niri has no way of knowing that, and will draw the shadow behind the entire surface, including the invisible margins.

To use niri shadows, you’ll need to configure layer-shell clients to remove their own margins or shadows.

// Add a shadow for fuzzel.
layer-rule {
    match namespace="^launcher$"

    shadow {
        on
    }

    // Fuzzel defaults to 10 px rounded corners.
    geometry-corner-radius 10
}

geometry-corner-radius

Available since version 25.02

geometry-corner-radius · number

Set the corner radius of the surface in logical pixels. This setting will only affect the shadow—it will round its corners to match the geometry corner radius.

layer-rule {
    match namespace="^launcher$"
    geometry-corner-radius 12
}

place-within-backdrop

Available since version 25.05

place-within-backdrop · boolean

Set to true to place the surface into the backdrop visible in the Overview and between workspaces. This will only work for background layer surfaces that ignore exclusive zones (typical for wallpaper tools). Layers within the backdrop will ignore all input.

// Put swaybg inside the overview backdrop.
layer-rule {
    match namespace="^wallpaper$"
    place-within-backdrop true
}

baba-is-float

Available since version 25.05

baba-is-float · boolean

Make your layer surfaces FLOAT up and down. This is a natural extension of the April Fools’ 2025 feature.

// Make fuzzel FLOAT.
layer-rule {
    match namespace="^launcher$"
    baba-is-float true
}