Hyprland Wiki
Contribute to the Wiki!Toggle Dark/Light/Auto modeToggle Dark/Light/Auto modeToggle Dark/Light/Auto modeBack to homepage

Window Rules

Table of contents

Disclaimers

Window rules (both V1 and V2) are case sensitive. (e.g. firefoxFirefox)

Window Rules V1

You can set window rules to achieve different behaviors from the active container.

Syntax

windowrule=RULE,WINDOW
  • RULE is a rule (and a param if applicable)
  • WINDOW is a RegEx, either:
    • plain RegEx (for matching a window class);
    • title: followed by a regex (for matching a window’s title)

Examples

windowrule=float,^(kitty)$
windowrule=move 0 0,title:^(Firefox)(.*)$

Window Rules V2

In order to allow more flexible rules, while retaining compatibility with the above rule system, window rules V2 were implemented.

In V2, you are allowed to match multiple variables.

the RULE field is unchanged, but in the WINDOW field, you can put regexes for multiple values like so:

windowrulev2 = float,class:(kitty),title:(kitty)

In the case of dynamic window titles such as browser windows keep in mind how powerful regex is.

for example a window rule of: windowrule=opacity 0.3 override 0.3 override,title:(.*)(- Youtube)$ will match any window that contains a string of “- Youtube” after any other text. This could be multiple browser windows or other applications that contain the string for any reason.

for the windowrulev2 = float,class:(kitty),title:(kitty) example, the class:(kitty) WINDOW field is what keeps the window rule specific to kitty terminals.

For now, the supported fields are:

class - class regex 
title - title regex
initialClass - initialClass regex
initialTitle - initialTitle regex
xwayland - 0/1
floating - 0/1
fullscreen - 0/1
pinned - 0/1
focus - 0/1
workspace - id or name: and name
onworkspace (how many windows are on the workspace) - int 

Keep in mind that you have to declare at least one field, but not all.

To get more information about a window’s class, title, XWayland status or its size, you can use hyprctl clients.

Rules

Static rules

Static rules are evaluated once at window open and never again.

RuleDescription
floatfloats a window
tiletiles a window
fullscreenfullscreens a window
fakefullscreenfakefullscreens a window
maximizemaximizes a window
move [x] [y]moves a floating window (x,y -> int or %, e.g. 20% or 100. You are also allowed to do 100%- for the right/bottom anchor, e.g. 100%-20). Additionally, you can also do cursor [x] [y] where x and y are either pixels or percent. Percent is calculated from the window’s size. Specify onscreen before other parameters to force the window into the screen (e.g. move onscreen cursor 50% 50%)
size [x] [y]resizes a floating window (x,y -> int or %, e.g. 20% or 100)
center ([opt])if the window is floating, will center it on the monitor. Set opt as 1 to respect monitor reserved area
pseudopseudotiles a window
monitor [id]sets the monitor on which a window should open. id can be either id or name (either e.g. 1 or e.g. DP-1)
workspace [w]sets the workspace on which a window should open (for workspace syntax, see dispatchers->workspaces). You can also make [w] to unset, will unset all previous workspace rules applied to this window. You can also add silent after the workspace to make the window open silently.
nofocusdisables focus to the window
noinitialfocusdisables the initial focus to the window
forceinputforces an XWayland window to receive input, even if it requests not to do so. (Might fix issues like e.g. Game Launchers not receiving focus for some reason)
windowdanceforces an XWayland window to never refocus, used for games/applications like Rhythm Doctor
pinpins the window (i.e. show it on all workspaces) note: floating only
unsetremoves all previously set rules for the given parameters. Please note it has to match EXACTLY.
nomaxsizeremoves max size limitations. Especially useful with windows that report invalid max sizes (e.g. winecfg)
stayfocusedforces focus on the window as long as it’s visible
group [options]set window group properties. See the note below.
suppressevent [types…]ignores specific events from the window. Events are space separated, and can be: fullscreen maximize activate activatefocus

Dynamic rules

Dynamic rules are re-evaluated every time a property changes.

RuleDescription
opacity [a]additional opacity multiplier. Options for a: float -> sets an opacity OR float float -> sets activeopacity and inactiveopacity respectively. You can also add override after an opacity to make it override instead of a multiplier. (e.g. 1.0 override 0.5 override)
opaqueforces the window to be opaque (can be toggled with the toggleopaque dispatcher)
forcergbxmakes hyprland ignore the alpha channel of all the window’s surfaces, effectively making it actually, fully 100% opaque
animation [style] ([opt])forces an animation onto a window, with a selected opt. Opt is optional.
rounding [x]forces the application to have X pixels of rounding, ignoring the set default (in decoration:rounding). Has to be an int.
minsize [x] [y]sets the minimum size (x,y -> int)
maxsize [x] [y]sets the maximum size (x,y -> int)
noblurdisables blur for the window
noborderdisables borders for the window
bordersize [size]sets the border size
nodimdisables window dimming for the window
noshadowdisables shadows for the window
noanimdisables the animations for the window
keepaspectratioforces aspect ratio when resizing window with the mouse
bordercolor [c]force the bordercolor of the window. Options for c: color/color ... color angle -> sets the active border color/gradient OR color color/color ... color angle color ... color [angle] -> sets the active and inactive border color/gradient of the window. See variables->colors for color definition.
idleinhibit [mode]sets an idle inhibit rule for the window. If active, apps like hypridle will not fire. Modes: none, always, focus, fullscreen
dimarounddims everything around the window . Please note this rule is meant for floating windows and using it on tiled ones may result in strange behavior.
xray [on]sets blur xray mode for the window (0 for off, 1 for on, unset for default)
immediateforces the window to allow to be torn. See the Tearing page.
nearestneighborforces the window to use the nearest neigbor filtering.

group window rule options

  • set [always] - Open window as a group.
  • new - Shorthand of barred set.
  • lock [always] - Lock the group that added this window. Use with set or new (i.e. new lock) to create a new locked group.
  • barred - Do not add the window to the focused group. By default, a window with a group set rule will be added to an active group if possible.
  • deny - Do not allow window to be toggled as or added to group (see denywindowfromgroup dispatcher).
  • invade - Force open window in the locked group.
  • override [other options] - Override other group rules, e.g. You can make all windows in a particular workspace open as a group, and use group override barred to make windows with specific titles open as normal windows.
  • unset - Clear all group rules.

The group rule without options is a shorthand for group set.

By default, set and lock only affect new windows once. The always qualifier makes them always effective.

Example Rules

windowrule = move 100 100,^(kitty)$ # moves kitty to 100 100
windowrule = animation popin,^(kitty)$ # sets the animation style for kitty
windowrule = noblur,^(firefox)$ # disables blur for firefox
windowrule = move cursor -50% -50%,^(kitty)$ # moves kitty to the center of the cursor
windowrulev2 = bordercolor rgb(FF0000) rgb(880808),fullscreen:1 # set bordercolor to red if window is fullscreen
windowrulev2 = bordercolor rgb(FFFF00),title:^(.*Hyprland.*)$ # set bordercolor to yellow when title contains Hyprland
windowrule = opacity 1.0 override 0.5 override,^(kitty)$ # set opacity to 1.0 active and 0.5 inactive for kitty
windowrule = rounding 10,^(kitty)$ # set rounding to 10 for kitty
windowrulev2 = stayfocused, class:^(pinentry-) # fix pinentry losing focus

Notes

Rules that are marked as Dynamic will be reevaluated if the matching property of the window changes. For instance, if a rule is defined that changes the bordercolor of a window when it is floating, then the bordercolor will change to the requested color when it is set to floating, and revert to the default color when it is tiled again.

Rules will be processed from top to bottom, where the last match will take precedence. i.e.

windowrulev2 = opacity 0.8 0.8,class:^(kitty)$
windowrulev2 = opacity 0.5 0.5,floating:1

-> all kitty windows will have opacity 0.8, except if they are floating. Then they will have opacity 0.5. -> all floating windows will have opacity 0.5.

windowrulev2 = opacity 0.5 0.5,floating:1
windowrulev2 = opacity 0.8 0.8,class:^(kitty)$

-> all kitty windows will have opacity 0.8, also if they are floating. -> all other floating windows will have opacity 0.5.

Opacity is always a PRODUCT of all opacities. E.g. active_opacity to 0.5 and windowrule opacity to 0.5 will result in a total opacity 0.25. You are allowed to set opacities over 1, but any opacity product over 1 will cause graphical glitches. E.g. 0.5 * 2 = 1, and it will be fine, 0.5 * 4 will cause graphical glitches.

Layer Rules

Some things in wayland are not windows, but layers. That includes for example most launchers, your status bar or wallpaper.

Those have specific rules separate from windows:

layerrule = rule, namespace
# or
layerrule = rule, address

where rule is the rule and namespace is the namespace regex (find namespaces in hyprctl layers) or address is an address in the form of address:0x[hex]

Rules

ruledescription
unsetremoves all layerRules previously set for a select namespace regex. Please note it has to match exactly
noanimdisables animations
blurenables blur for the layer
ignorealpha [a]makes blur ignore pixels with opacity of a or lower. a is float value from 0 to 1. a = 0 if unspecified.
ignorezeromakes blur ignore fully transparent pixels. Same as ignorealpha 0.
xray [on]sets the blur xray mode for a layer. 0 for off, 1 for on, unset for default.
animation [style]allows you to set a specific animation style for this layer