Window Rules
Match windows and set how they open or how they look
sweets.window_rule matches windows and sets how they open or look.
sweets.window_rule({ app_id = "org.wezfurlong.wezterm", workspace = 2 })
sweets.window_rule({ title = "Picture-in-Picture", floating = true, focus = false })
sweets.window_rule({ app_id = "foot", opacity = 0.88, blur = true })For panels, launchers, and wallpapers, use
sweets.layer_rule.
Finding a window's app ID
sweets msg windows # list windows, their IDs and app IDs
sweets msg window-rule WINDOW_ID # which rules matched one windowMatching
| Field | Matches |
|---|---|
app_id | App ID, or X11 class for X11 apps |
instance | X11 instance, independently of its class |
title | Window title when it opened |
sandbox_engine | Sandbox launcher, such as "org.flatpak" |
sandbox_app_id | App ID supplied by the sandbox launcher |
backend | "xdg" (Wayland) or "xwayland" (X11) |
dialog | true for dialogs |
transient | true for windows with a parent |
at_startup | true for windows opened in the first 60 seconds of the session |
All fields in a rule must match. A plain string must match exactly. Titles
often change, so prefer app_id.
Patterns
sweets.window_rule({ app_id = { prefix = "org.mozilla." }, opacity = 0.95 })
sweets.window_rule({ title = { contains = "Picture-in-Picture" }, floating = true })
sweets.window_rule({ app_id = { suffix = ".Devtools", ignore_case = true }, workspace = 3 })Use one of exact, prefix, suffix, or contains. Add ignore_case = true
to ignore case.
X11 instances
xterm -class XTerm -name scratch matches this rule while a normal XTerm does
not:
sweets.window_rule({ app_id = "XTerm", instance = "scratch", floating = true })
sweets.bind("MOD+Alt+S", "focus_window", { instance = "scratch" })instance supports the same patterns and exclusions. Native Wayland windows
and X11 windows without an instance never match it. Rules use the instance
the window had when it opened.
Sandboxed apps
sweets.window_rule({
sandbox_engine = "org.flatpak",
sandbox_app_id = "org.mozilla.firefox",
workspace = 2,
})Sandbox fields come from the launcher and stay fixed for the connection. They support the same patterns and exclusions. Direct Wayland and X11 clients have no sandbox identity and cannot match these fields.
Exclusions
exclude skips windows that match it:
sweets.window_rule({
app_id = { suffix = "term" },
exclude = { title = { contains = "mpv" } },
blur = true,
})
-- Everything except mpv.
sweets.window_rule({ exclude = { app_id = "mpv" }, blur = true })
-- Several exclusions.
sweets.window_rule({
app_id = "chromium",
exclude = { { dialog = true }, { title = "Save File" } },
workspace = 2,
})Rule order
Every matching rule applies, top to bottom. If two rules set the same property, the later one wins:
sweets.window_rule({ dialog = true, floating = true, focus = false })
sweets.window_rule({ app_id = "org.example.Editor", dialog = true, focus = true })An editor dialog floats (first rule) and takes focus (second rule).
A later rule can't remove a property, only change it. Use exclude to keep a
rule off a window.
Opening properties
These apply when a window opens. After changing one, reopen the app.
| Field | Effect |
|---|---|
workspace | Open on workspace 1–10 |
monitor | Open on a monitor |
special | Open in a named special workspace, hidden |
floating | true floats, false tiles |
size | Floating size, { width, height } |
position | Floating position: an anchor, { x, y }, or "pointer" |
min_size, max_size | Size limits, { width, height } |
keep_aspect_ratio | Keep the shape while resizing a floating window |
remember_geometry | Reopen where you left it |
maximized | Open maximized |
fullscreen | Open fullscreen |
pin | Show on every workspace |
focus | false opens without taking focus |
focus_on_hover | false keeps keyboard focus elsewhere when the pointer enters; defaults to true |
stacking | "above" or "below" other windows |
group | false never joins a tab group, true joins the focused one |
column_width | Column width in the scrolling layout |
corner_radius | Rounded corners for this window |
decorations | "client" lets a Wayland app draw its own title bar |
scroll_factor | Scroll speed for this window, 0.01–10 |
touchpad_scroll_factor | Touchpad scroll speed for this window, 0.01–10 |
pinch_factor | Touchpad pinch-zoom speed, 0.01–10; default 1.0 |
adaptive_sync | Allow VRR while fullscreen |
animation | false turns off animations |
on_xdg_activate | What happens when the app asks for focus |
shortcuts_inhibit | false stops the app grabbing your shortcuts |
maximize_requests, minimize_requests, fullscreen_requests | false blocks the app from changing these itself |
stacking_requests | false stops an X11 app keeping itself on top |
close_protection_ms | Ignore close requests for this many milliseconds after opening, up to 5000 |
Sweets floats windows with a fixed size automatically. Set floating = false to
tile them anyway.
Scroll speed
sweets.window_rule({ app_id = "firefox", touchpad_scroll_factor = 0.6 })touchpad_scroll_factor replaces the window's scroll_factor during touchpad
scrolling. A mouse wheel uses scroll_factor. Sweets also applies the
device setting.
Use a number for both axes or a table such as { vertical = 0.6 }. Axes left out
of a table use 1.0.
Pinch zoom
sweets.window_rule({ app_id = "firefox", pinch_factor = 0.75 })Values below 1.0 slow pinch zoom; values above it speed it up.
The app must support native Wayland pinch gestures. Scrolling is unchanged.
Reopen the window after changing the rule.
Hover focus
Keep typing while the pointer passes over a picture-in-picture window:
sweets.window_rule({ title = "Picture-in-Picture", floating = true, focus_on_hover = false })Clicks and keyboard selection still focus it. Its menus follow the same setting. Reopen the window after changing the rule.
Placement
sweets.window_rule({ app_id = "steam", monitor = "DP-1" })
sweets.window_rule({ app_id = "spotify", special = "music" })monitortakes a connector name, ormake,model, andserialfromsweets msg outputs.- Use only one of
workspace,monitor, orspecialper rule. - Dialogs stay with their parent window unless the rule matches
dialogortransient.
Size and position
sweets.window_rule({ app_id = "mpv", size = { 960, 540 }, position = "bottom-right" })
sweets.window_rule({ app_id = "pavucontrol", size = { 0.5, 0.6 }, position = "center" })- A number up to
1is a share of the screen. Above1it's pixels. positionanchors:center,top,bottom,left,right,top-left,top-right,bottom-left,bottom-right.- Inset from an anchor:
position = { anchor = "bottom-right", x = 32, y = 32 }. sizeandpositionmake the window float.
Remembering where a window was
sweets.window_rule({ app_id = "org.gnome.Nautilus", floating = true, remember_geometry = true })- The window reopens where it was last closed, at the same size. Logging out with it open counts as closing it.
- Each monitor keeps its own spot.
- A second window of the same app opens normally.
- Close it while it's tiled to forget the spot.
sizeorpositionin a rule always win.
Pinning a window
A pinned window stays on screen when you switch workspaces. It's useful for Picture-in-Picture.
sweets.window_rule({
title = "Picture-in-Picture",
pin = true,
size = { 480, 270 },
position = "bottom-right",
})
sweets.bind("MOD+P", "toggle_pin")Only floating windows can be pinned. Maximizing, fullscreening, or tiling the
window unpins it. You can also pin a window by ID with
sweets msg set-window-pinned 42 on.
Focus requests
on_xdg_activate decides what happens when an app asks for focus:
| Value | Effect |
|---|---|
"ignore" | Nothing |
"set_urgent" | Mark it urgent, don't focus |
"focus" | Focus it |
sweets.window_rule({ title = "Picture-in-Picture", on_xdg_activate = "set_urgent" })Appearance properties
These update on reload, no reopening needed.
| Field | Effect |
|---|---|
opacity | Opacity, or { focused, unfocused, dragged, fullscreen } |
dim_inactive | Darken the window when unfocused, or false |
blur | true or false |
blur_mode | "optimized" or "scene" |
shadow | true or false |
border | Border for this window, or false |
dim_around | Darken the screen behind it |
popups | Style its menus |
idle_inhibit | Keep the screen awake |
render_unfocused | Keep drawing while hidden |
block_out_from, block_out_style | Hide from screen captures |
blur and shadow also need sweets.blur
and sweets.shadow turned on.
Per-window borders
border takes the same fields as
sweets.border. Fields you skip keep
the global value.
-- Hard to miss on your password manager.
sweets.window_rule({
app_id = "org.keepassxc.KeePassXC",
border = { focused = "#F7768E", unfocused = "#7D0D2D" },
})
-- No border on videos.
sweets.window_rule({ app_id = "mpv", border = false })Fullscreen windows never have a border.
Dimming behind a window
dim_around darkens the screen behind a floating window, so a prompt stands
out.
sweets.window_rule({ app_id = "gcr-prompter", floating = true, dim_around = "#000000B3" })Keeping the screen awake
idle_inhibit stops the screen from blanking while the window is visible.
Most Wayland video players do this on their own. Use it for apps that don't.
sweets.window_rule({ backend = "xwayland", app_id = "vlc", idle_inhibit = "fullscreen" })| Value | Keeps the screen awake |
|---|---|
"none" | Never (default) |
"always" | While visible |
"focus" | While visible and focused |
"fullscreen" | While visible and fullscreen |
Keeping a hidden window drawing
Some apps stop drawing when they're not on screen. If you share one in a call
and switch workspaces, the call sees a frozen image. render_unfocused keeps
it drawing.
sweets.window_rule({ app_id = "org.mozilla.firefox", render_unfocused = true })Set it on the window you share, not on the recording app. The frame rate is
render_unfocused_fps.
Hiding a window from captures
block_out_from chooses which screen captures block the window and its popups.
The window stays visible on your screen.
sweets.window_rule({
app_id = "org.keepassxc.KeePassXC",
block_out_from = "screen_capture",
block_out_style = "hide",
})The default style, "black", draws a black box. "hide" shows what is behind
the window. Capturing that window by itself gives a transparent image.
| Value | Hidden from |
|---|---|
"none" | Nothing |
"screencast" | Screen sharing and recording. Some screenshot tools, like grim, too |
"screen_capture" | Every capture, screenshots included |
This helps avoid accidents. It is not a security guarantee.
Popups
popups styles the window's menus and tooltips:
sweets.window_rule({
app_id = "org.gnome.Nautilus",
popups = { opacity = 0.9, blur = true, corner_radius = 18 },
})It takes opacity, blur, blur_mode, and corner_radius.
Animations
animation = false turns off opening, closing, and minimizing animations for a
window. A table changes them instead:
sweets.window_rule({ app_id = "gcr-prompter", animation = false })
sweets.window_rule({ app_id = "dropdown", animation = {
open = { type = "slide", direction = "down", duration = 260 },
minimize = false,
} })open, close, and minimize take the same fields as
animations, except type = "shader" and shader.
Blocking app requests
Stop an app from grabbing your shortcuts, or from changing its own state:
sweets.window_rule({ app_id = "org.gnome.Boxes", shortcuts_inhibit = false })
sweets.window_rule({
app_id = "org.example.Game",
maximize_requests = false,
minimize_requests = false,
fullscreen_requests = false,
})Your own bindings still work on these windows.
Some X11 apps, often Wine games, keep themselves above every other window.
stacking_requests = false stops that. Add stacking = "normal" to also drop
it when the window opens:
sweets.window_rule({
app_id = { suffix = ".exe" },
stacking = "normal",
stacking_requests = false,
})toggle_above and toggle_below still work on these windows.
Some games break if fullscreen is refused. Test before keeping that rule.