Sweets

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 window

Matching

FieldMatches
app_idApp ID, or X11 class for X11 apps
instanceX11 instance, independently of its class
titleWindow title when it opened
sandbox_engineSandbox launcher, such as "org.flatpak"
sandbox_app_idApp ID supplied by the sandbox launcher
backend"xdg" (Wayland) or "xwayland" (X11)
dialogtrue for dialogs
transienttrue for windows with a parent
at_startuptrue 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.

FieldEffect
workspaceOpen on workspace 1–10
monitorOpen on a monitor
specialOpen in a named special workspace, hidden
floatingtrue floats, false tiles
sizeFloating size, { width, height }
positionFloating position: an anchor, { x, y }, or "pointer"
min_size, max_sizeSize limits, { width, height }
keep_aspect_ratioKeep the shape while resizing a floating window
remember_geometryReopen where you left it
maximizedOpen maximized
fullscreenOpen fullscreen
pinShow on every workspace
focusfalse opens without taking focus
focus_on_hoverfalse keeps keyboard focus elsewhere when the pointer enters; defaults to true
stacking"above" or "below" other windows
groupfalse never joins a tab group, true joins the focused one
column_widthColumn width in the scrolling layout
corner_radiusRounded corners for this window
decorations"client" lets a Wayland app draw its own title bar
scroll_factorScroll speed for this window, 0.01–10
touchpad_scroll_factorTouchpad scroll speed for this window, 0.01–10
pinch_factorTouchpad pinch-zoom speed, 0.01–10; default 1.0
adaptive_syncAllow VRR while fullscreen
animationfalse turns off animations
on_xdg_activateWhat happens when the app asks for focus
shortcuts_inhibitfalse stops the app grabbing your shortcuts
maximize_requests, minimize_requests, fullscreen_requestsfalse blocks the app from changing these itself
stacking_requestsfalse stops an X11 app keeping itself on top
close_protection_msIgnore 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" })
  • monitor takes a connector name, or make, model, and serial from sweets msg outputs.
  • Use only one of workspace, monitor, or special per rule.
  • Dialogs stay with their parent window unless the rule matches dialog or transient.

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 1 is a share of the screen. Above 1 it's pixels.
  • position anchors: 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 }.
  • size and position make 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.
  • size or position in 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:

ValueEffect
"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.

FieldEffect
opacityOpacity, or { focused, unfocused, dragged, fullscreen }
dim_inactiveDarken the window when unfocused, or false
blurtrue or false
blur_mode"optimized" or "scene"
shadowtrue or false
borderBorder for this window, or false
dim_aroundDarken the screen behind it
popupsStyle its menus
idle_inhibitKeep the screen awake
render_unfocusedKeep drawing while hidden
block_out_from, block_out_styleHide 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" })
ValueKeeps 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.

ValueHidden 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.

On this page