Window Rules

Configure behavior and appearance for specific windows using matchers and properties

Overview

Window rules let you adjust behavior for individual windows. They have match and exclude directives that control which windows the rule should apply to, and a number of properties that you can set.

Window rules are processed in order of appearance in the config file. This means that you can put more generic rules first, then override them for specific windows later.

// Set open-maximized to true for all windows.
window-rule {
    open-maximized true
}

// Then, for Alacritty, set open-maximized back to false.
window-rule {
    match app-id="Alacritty"
    open-maximized false
}

In general, you cannot “unset” a property in a later rule, only set it to a different value. Use the exclude directives to avoid applying a rule for specific windows.

Window Matching

Each window rule can have several match and exclude directives. In order for the rule to apply, a window needs to match any of the match directives, and none of the exclude directives.

window-rule {
    // Match all Telegram windows...
    match app-id=r#"^org\.telegram\.desktop$"#

    // ...except the media viewer window.
    exclude title="^Media viewer$"

    // Properties to apply.
    open-on-output "HDMI-A-1"
}

Finding Window Info

You can find the title and the app ID of a window by running:

niri msg pick-window

Then click on the window in question.

Matchers

title and app-id

These are regular expressions that should match anywhere in the window title and app ID respectively.

// Match windows with title containing "Mozilla Firefox",
// or windows with app ID containing "Alacritty".
window-rule {
    match title="Mozilla Firefox"
    match app-id="Alacritty"
}

Raw KDL strings can be helpful for writing out regular expressions:

window-rule {
    exclude app-id=r#"^org\.keepassxc\.KeePassXC$"#
}

is-active

Can be true or false. Matches active windows (same windows that have the active border / focus ring color).

window-rule {
    match is-active=true
}

Every workspace on the focused monitor will have one active window. This means that you will usually have multiple active windows.

is-focused

Can be true or false. Matches the window that has the keyboard focus.

window-rule {
    match is-focused=true
}

Contrary to is-active, there can only be a single focused window. Also, when opening a layer-shell application launcher or pop-up menu, the keyboard focus goes to layer-shell.

is-active-in-column

Can be true or false. Matches the window that is the “active” window in its column.

window-rule {
    match is-active-in-column=true
}

Contrary to is-active, there is always one is-active-in-column window in each column. It is the window that was last focused in the column.

This rule will match true during the initial window opening.

is-floating

Can be true or false. Matches floating windows.

window-rule {
    match is-floating=true
}

This matcher will apply only after the window is already open. This means that you cannot use it to change the window opening properties like default-window-height or open-on-workspace.

is-window-cast-target

Can be true or false. Matches true for windows that are target of an ongoing window screencast.

// Indicate screencasted windows with red colors.
window-rule {
    match is-window-cast-target=true

    focus-ring {
        active-color "#f38ba8"
        inactive-color "#7d0d2d"
    }
}

This only matches individual-window screencasts. It will not match windows that happen to be visible in a monitor screencast.

is-urgent

Can be true or false. Matches windows that request the user’s attention.

window-rule {
    match is-urgent=true
}

at-startup

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

// Open windows on the HDMI-A-1 monitor at niri startup, but not afterwards.
window-rule {
    match at-startup=true
    open-on-output "HDMI-A-1"
}

This is useful for properties like open-on-output which you may want to apply only right after starting niri.

Window Opening Properties

These properties apply once, when a window first opens.

default-column-width

Set the default width for the new window. This works for floating windows too, despite the word “column” in the name.

// Give Blender and GIMP some guaranteed width on opening.
window-rule {
    match app-id="^blender$"
    match app-id="^gimp"

    default-column-width { fixed 1200; }
}

default-window-height

Set the default height for the new window.

// Open the Firefox picture-in-picture window as floating with 480×270 size.
window-rule {
    match app-id="firefox$" title="^Picture-in-Picture$"

    open-floating true
    default-column-width { fixed 480; }
    default-window-height { fixed 270; }
}

open-on-output

Make the window open on a specific output.

// Open Firefox and Telegram on a specific monitor.
window-rule {
    match app-id="firefox$"
    match app-id=r#"^org\.telegram\.desktop$"#
    exclude app-id=r#"^org\.telegram\.desktop$"# title="^Media viewer$"

    open-on-output "HDMI-A-1"
    // Or:
    // open-on-output "Some Company CoolMonitor 1234"
}

If such an output does not exist, the window will open on the currently focused output as usual.

open-on-output can now use monitor manufacturer, model, and serial.

open-on-workspace

Make the window open on a specific named workspace.

// Open Fractal on the "chat" workspace.
window-rule {
    match app-id=r#"^org\.gnome\.Fractal$"#

    open-on-workspace "chat"
}

open-maximized

Make the window open as a maximized column.

// Maximize Firefox by default.
window-rule {
    match app-id="firefox$"

    open-maximized true
}

open-maximized-to-edges

Make the window open maximized to edges.

window-rule {
    open-maximized-to-edges true
}

You can also set this to false to prevent a window from opening maximized to edges.

open-fullscreen

Make the window open fullscreen.

window-rule {
    open-fullscreen true
}

You can also set this to false to prevent a window from opening fullscreen:

// Make the Telegram media viewer open in windowed mode.
window-rule {
    match app-id=r#"^org\.telegram\.desktop$"# title="^Media viewer$"

    open-fullscreen false
}

open-floating

Make the window open in the floating layout.

// Open the Firefox picture-in-picture window as floating.
window-rule {
    match app-id="firefox$" title="^Picture-in-Picture$"

    open-floating true
}

open-focused

Set this to false to prevent this window from being automatically focused upon opening.

// Don't give focus to the GIMP startup splash screen.
window-rule {
    match app-id="^gimp" title="^GIMP Startup$"

    open-focused false
}

Dynamic Properties

These properties apply continuously to open windows.

opacity

Set the opacity of the window. 0.0 is fully transparent, 1.0 is fully opaque.

// Make inactive windows semitransparent.
window-rule {
    match is-active=false

    opacity 0.95
}

Opacity is applied on top of the window’s own opacity, so semitransparent windows will become even more transparent.

Opacity can be toggled on or off for a window using the toggle-window-rule-opacity action.

block-out-from

You can block out windows from xdg-desktop-portal screencasts. They will be replaced with solid black rectangles.

// Block out password managers from screencasts.
window-rule {
    match app-id=r#"^org\.keepassxc\.KeePassXC$"#
    match app-id=r#"^org\.gnome\.World\.Secrets$"#

    block-out-from "screencast"
}

Alternatively, you can block out the window from all screen captures:

window-rule {
    block-out-from "screen-capture"
}

The window is not blocked out from third-party screenshot tools. If you open some screenshot tool with preview while screencasting, blocked out windows will be visible on the screencast.

Be careful when blocking out windows based on a dynamically changing window title. When switching tabs, the old tab contents may show up on a screencast for an instant because window title is not double-buffered in the Wayland protocol.

variable-refresh-rate

If set to true, whenever this window displays on an output with on-demand VRR, it will enable VRR on that output.

// Configure some output with on-demand VRR.
output "HDMI-A-1" {
    variable-refresh-rate on-demand=true
}

// Enable on-demand VRR when mpv displays on the output.
window-rule {
    match app-id="^mpv$"

    variable-refresh-rate true
}

default-column-display

Set the default display mode for columns created from this window. Can be normal or tabbed.

// Make Evince windows open as tabbed columns.
window-rule {
    match app-id="^evince$"

    default-column-display "tabbed"
}

geometry-corner-radius

Set the corner radius of the window.

window-rule {
    geometry-corner-radius 12
}

Instead of one radius, you can set four, for each corner (top-left, top-right, bottom-right, bottom-left):

window-rule {
    geometry-corner-radius 8 8 0 0
}

On its own, this setting will only affect the border and the focus ring. If you’d like to force-round the corners of the window itself, set clip-to-geometry true in addition to this setting.

clip-to-geometry

Clips the window to its visual geometry. This will cut out any client-side window shadows, and also round window corners according to geometry-corner-radius.

window-rule {
    clip-to-geometry true
}

Size Overrides

You can amend the window’s minimum and maximum size in logical pixels.

window-rule {
    min-width 100
    max-width 200
    min-height 300
    max-height 300
}

// Fix OBS with server-side decorations missing a minimum width.
window-rule {
    match app-id=r#"^com\.obsproject\.Studio$"#

    min-width 876
}

Keep in mind that the window itself always has a final say in its size. These values instruct niri to never ask the window to be smaller than the minimum you set, or to be bigger than the maximum you set.

max-height will only apply to automatically-sized windows if it is equal to min-height.

Example Configurations

WezTerm Initial Configure Workaround

window-rule {
    match app-id=r#"^org\.wezfurlong\.wezterm$"#
    default-column-width {}
}

Firefox Picture-in-Picture

window-rule {
    match app-id=r#"firefox$"# title="^Picture-in-Picture$"
    open-floating true
    default-column-width { fixed 480; }
    default-window-height { fixed 270; }
}

Password Manager Privacy

window-rule {
    match app-id=r#"^org\.keepassxc\.KeePassXC$"#
    match app-id=r#"^org\.gnome\.World\.Secrets$"#

    block-out-from "screen-capture"
}

Rounded Corners for All Windows

window-rule {
    geometry-corner-radius 12
    clip-to-geometry true
}