1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
|
### Overview
<sup>Since: 25.01</sup>
Layer rules let you adjust behavior for individual layer-shell surfaces.
They have `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 wiki page](./Configuration:-Window-Rules.md) to learn how matching works.
Here are all matchers and properties that a layer rule could have:
```kdl
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
Let's look at the matchers in more detail.
#### `namespace`
This is a regular expression that should match anywhere in the surface namespace.
You can read about the supported regular expression syntax [here](https://docs.rs/regex/latest/regex/#syntax).
```kdl
// Match surfaces with namespace containing "waybar",
layer-rule {
match namespace="waybar"
}
```
You can find the namespaces of all open layer-shell surfaces by running `niri msg layers`.
#### `at-startup`
Can be `true` or `false`.
Matches during the first 60 seconds after starting niri.
```kdl
// 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`
You can block out surfaces from xdg-desktop-portal screencasts or all screen captures.
They will be replaced with solid black rectangles.
This can be useful for notifications.
The same caveats and instructions apply as for the [`block-out-from` window rule](./Configuration:-Window-Rules.md#block-out-from), so check the documentation there.
```kdl
// Block out mako notifications from screencasts.
layer-rule {
match namespace="^notifications$"
block-out-from "screencast"
}
```
#### `opacity`
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.
```kdl
// Make fuzzel semitransparent.
layer-rule {
match namespace="^launcher$"
opacity 0.95
}
```
#### `shadow`
<sup>Since: 25.02</sup>
Override the shadow options for the surface.
These rules have the same options as the normal [`shadow` config in the layout section](./Configuration:-Layout.md#shadow), so check the documentation there.
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]
> 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.
>
> So to use niri shadows, you'll need to configure layer-shell clients to remove their own margins or shadows.
```kdl
// 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`
<sup>Since: 25.02</sup>
Set the corner radius of the surface.
This setting will only affect the shadow—it will round its corners to match the geometry corner radius.
```kdl
layer-rule {
match namespace="^launcher$"
geometry-corner-radius 12
}
```
#### `place-within-backdrop`
<sup>Since: 25.05</sup>
Set to `true` to place the surface into the backdrop visible in the [Overview](./Overview.md) 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.
```kdl
// Put swaybg inside the overview backdrop.
layer-rule {
match namespace="^wallpaper$"
place-within-backdrop true
}
```
#### `baba-is-float`
<sup>Since: 25.05</sup>
Make your layer surfaces FLOAT up and down.
This is a natural extension of the [April Fools' 2025 feature](./Configuration:-Window-Rules.md#baba-is-float).
```kdl
// Make fuzzel FLOAT.
layer-rule {
match namespace="^launcher$"
baba-is-float true
}
```
|
