> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/niri-wm/niri/llms.txt
> Use this file to discover all available pages before exploring further.

# Layer Rules

> Configure behavior for individual layer-shell surfaces in niri

<Info>
  Available since version 25.01
</Info>

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](/configuration/window-rules) to learn how matching works.

## Configuration Structure

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

```kdl theme={null}
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

<ParamField path="namespace" type="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`.
</ParamField>

```kdl theme={null}
// 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](https://docs.rs/regex/latest/regex/#syntax).

### at-startup

<ParamField path="at-startup" type="boolean">
  Matches during the first 60 seconds after starting niri. Can be `true` or `false`.
</ParamField>

```kdl theme={null}
// 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

<ParamField path="block-out-from" type="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
</ParamField>

This can be useful for notifications. The same caveats and instructions apply as for the [block-out-from window rule](/configuration/window-rules#block-out-from).

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

### opacity

<ParamField path="opacity" type="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.
</ParamField>

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

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

### shadow

<Info>
  Available since version 25.02
</Info>

<ParamField path="shadow" type="object">
  Override the shadow options for the surface. These rules have the same options as the normal [shadow config in the layout section](/configuration/layout#shadow).
</ParamField>

<Note>
  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.
</Note>

<Warning>
  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.
</Warning>

```kdl theme={null}
// 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

<Info>
  Available since version 25.02
</Info>

<ParamField path="geometry-corner-radius" type="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.
</ParamField>

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

### place-within-backdrop

<Info>
  Available since version 25.05
</Info>

<ParamField path="place-within-backdrop" type="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.
</ParamField>

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

### baba-is-float

<Info>
  Available since version 25.05
</Info>

<ParamField path="baba-is-float" type="boolean">
  Make your layer surfaces FLOAT up and down. This is a natural extension of the [April Fools' 2025 feature](/configuration/window-rules#baba-is-float).
</ParamField>

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