hyprwinwrap-toggle

context

i just wanted to run a chill game as my wallpaper.

but the problem was obvious: either it stays interactive and steals focus, or it behaves like a background and you cannot actually use it.

there was no middle ground.

so the idea became: what if i could switch between those two states whenever i wanted.

at some point, that idea turned into fixing compatibility issues with newer hyprland versions, and somehow i ended up maintaining a plugin without really planning to.

what it does

it lets you run a wayland app as a dynamic wallpaper, while being able to toggle its interactivity in real time.

when it is not interactable, it behaves like a normal background.

when it is, it acts like a regular window with full input.

features

• runs apps as wallpaper-like background surfaces
• toggle interactivity at runtime
• supports mouse, keyboard, and drag & drop when enabled
• handles focus without breaking the rest of the workspace
• fixes stacking issues with scratchpads and special workspaces
• keeps compatibility with newer hyprland versions

visuals

expand ↗

expand ↗

process

this started as just getting the plugin to work again.

hyprland had changed enough that the original code no longer compiled cleanly, so part of the work was adapting headers and making things compatible with newer versions.

from there, it became more about behavior.

making sure the window could act like a wallpaper without breaking focus, handling input correctly, and avoiding weird issues with stacking and special workspaces.

one of the tricky parts was controlling when the window should receive input and when it should not, without causing flickering or losing focus unexpectedly.

another was making sure it only rendered where it should, avoiding issues across monitors and workspaces.

over time it went from "just fix it" to actually understanding how hyprland handles windows, rendering, and input internally.

how to use

⚠️ Obsolete: The installation guide below should not be followed due to Hyprland's migration to Lua.

Install

Using hyprpm

Update plugin headers:

hyprpm update

Add this repository:

hyprpm add https://github.com/onlymikey/hyprwinwrap-toggle

Enable the plugin:

hyprpm enable hyprwinwrap-toggle

For more details, see:

https://wiki.hyprland.org/Plugins/Using-Plugins/#installing--using-plugins
hyprpm -h

Dispatch

hyprctl dispatch hyprwinwrap_toggle

This toggles input handling for all managed background windows.

Configuration

Configuration follows the original hyprwinwrap semantics.

See upstream-style options here:

hyprwinwrap/README.md

Typical usage is matching a window by class or title and letting the plugin manage it as a background surface.

Toggling interactivity

Example keybind:

bind = SUPER, L, exec, hyprctl dispatch hyprwinwrap_toggle

When disabled, the window behaves like a wallpaper. When enabled, the window accepts mouse and keyboard input normally.

stack

• c++
• hyprland plugin api
• wayland / wlroots
• hyprland render hooks

notes

depends on hyprland internals, so changes upstream can break things.

mainly focused on input behavior and compatibility.

rendering behavior mostly follows upstream.

links