Skip to Content
reference-yysui1kWindow Rules

Last Updated: 3/12/2026

Window Rules

Window rules let you automatically control window behavior based on criteria like class, title, or type. Use them to set floating mode, workspace assignment, opacity, size, and more.

Window Rule Syntax

Hyprland supports two syntaxes for window rules:

windowrule {
    name = rule-name        # Optional identifier
    match:class = pattern   # Match criteria
    match:title = pattern   # Additional criteria
    
    # Properties to apply
    float = yes
    size = 800 600
    move = 100 100
}

Legacy Syntax

windowrule = PROPERTY, PATTERN
windowrulev2 = PROPERTY, CRITERIA

The modern syntax is more readable and supports complex matching. Both work, but new configs should use the modern syntax.

Match Criteria

Common Match Fields

  • match:class: Window class (app identifier)
  • match:title: Window title
  • match:xwayland: Match XWayland windows (true/false)
  • match:float: Match floating windows (true/false)
  • match:fullscreen: Match fullscreened windows (true/false)
  • match:workspace: Match windows on specific workspace

Pattern Matching

Patterns support regex:

match:class = firefox       # Exact match
match:class = ^firefox$     # Regex exact match
match:class = .*terminal.*  # Contains "terminal"

Common Window Rules

Floating Windows

Make specific apps always float:

windowrule {
    name = float-calculator
    match:class = ^(gnome-calculator|qalculate-gtk)$
    
    float = yes
}

Window Size and Position

Set initial size and position:

windowrule {
    name = centered-terminal
    match:class = floating-term
    
    float = yes
    size = 800 600
    center = yes
}

windowrule {
    name = positioned-window
    match:class = my-app
    
    move = 100 100
    size = 1200 800
}

Workspace Assignment

Send windows to specific workspaces:

windowrule {
    name = browser-workspace
    match:class = ^(firefox|chromium)$
    
    workspace = 2
}

windowrule {
    name = music-workspace
    match:class = spotify
    
    workspace = 9 silent  # Don't switch to workspace 9
}

Opacity

Set window transparency:

windowrule {
    name = transparent-terminal
    match:class = kitty
    
    opacity = 0.9
}

Disable Effects

Suppress specific window events or effects:

windowrule {
    name = suppress-maximize-events
    match:class = .*
    
    suppress_event = maximize
}

Borders and Rounding

Customize per-window appearance:

windowrule {
    name = no-border-floating
    match:float = true
    match:workspace = w[tv1]
    
    border_size = 0
    rounding = 0
}

Focus Behavior

Control focus behavior:

windowrule {
    name = fix-xwayland-drags
    match:class = ^$
    match:title = ^$
    match:xwayland = true
    match:float = true
    match:fullscreen = false
    
    no_focus = true
}

Example Window Rules

From the Example Config

The example config includes these useful rules:

Suppress maximize events (recommended):

windowrule {
    name = suppress-maximize-events
    match:class = .*
    
    suppress_event = maximize
}

Prevents apps from requesting fullscreen when they shouldn’t.

Fix XWayland drag issues:

windowrule {
    name = fix-xwayland-drags
    match:class = ^$
    match:title = ^$
    match:xwayland = true
    match:float = true
    match:fullscreen = false
    match:pin = false
    
    no_focus = true
}

Fixes dragging issues with some XWayland apps.

Custom app positioning:

windowrule {
    name = move-hyprland-run
    match:class = hyprland-run
    
    move = 20 monitor_h-120
    float = yes
}

Advanced Matching

Multiple Criteria

Combine criteria for precise matching:

windowrule {
    name = floating-dialog
    match:class = firefox
    match:title = ^(Library|About).*
    
    float = yes
}

Workspace-Specific Rules

Apply rules only on certain workspaces:

windowrule {
    name = no-gaps-fullscreen
    match:workspace = f[1]
    match:float = false
    
    border_size = 0
    rounding = 0
}

Available Properties

  • float: yes/no — Floating mode
  • fullscreen: yes/no — Fullscreen mode
  • size: WIDTH HEIGHT — Window dimensions
  • move: X Y — Window position
  • center: yes — Center on screen
  • workspace: NUMBER [silent] — Workspace assignment
  • opacity: 0.0-1.0 — Transparency
  • border_size: PIXELS — Border width
  • rounding: PIXELS — Corner rounding
  • no_focus: true/false — Prevent focus
  • suppress_event: EVENT — Suppress window events
  • pin: yes — Pin window on all workspaces

Debugging Window Rules

Find Window Class and Title

Use hyprctl to inspect windows:

hyprctl clients

Look for class and title fields in the output. Use these values in your match criteria.

Test Rules Live

Use hyprctl keyword to test rules without editing your config:

hyprctl keyword windowrule float,^(my-app)$

Once confirmed, add to your config file.

Tips

  1. Start specific, then generalize: Match exact class first, then use regex if needed
  2. Use descriptive names: The name field helps document your rules
  3. Check for conflicts: Later rules can override earlier ones
  4. Test with hyprctl: Verify window class/title before writing rules
  5. Group related rules: Keep workspace-specific rules together

What’s Next

Explore Workspace Management to learn about dynamic workspaces, special workspaces, and workspace rules.

DecorationsHyprctl Cli